【译】JSON API for WP 文档翻译


1.基本概念

1.1 Requsets 请求

使用一个简单的rest风格的HTTP GET或POST请求。查询调用API,包括一个非空值json在URL中。

JSON API 有两种方式:

  • 隐式:通过设置JSON的参数查询WP页面上的任何一个非空值,通常会以JSON格式的方式返回这个页面的内容;
  • 显式:通过设置JSON触发一个已知的方法。见第二节:一个完整的请求方法列表。

1. 隐式调用

  • http://www.example.org/?json=1(返回该站全部json格式数据)
  • http://www.example.org/?p=47&json=1(返回文章id为47的json数据)
  • http://www.example.org/tag/banana/?json=1(返回标签是banana的json数据)

2. 显示调用

  • http://www.example.org/?json=getrecentposts(返回最新文章json数据,默认返回很多字段,可以指定)
  • http://www.example.org/?json=getpost&postid=47(返回id为47的文章json数据)
  • http://www.example.org/?json=gettagposts&tag_slug=banana(返回tag标签是banana的json数据)

    注意:这里的方法用下划线 _ 和短连接符 - 都可以。

3. 链接友好型调用

  • http://www.example.org/api/getrecentposts/
  • http://www.example.org/api/getpost/?postid=47
  • http://www.example.org/api/gettagposts/?tag_slug=banana

    注意:这里必须用下划线 _ ,不允许用短连接符 - 。

进一步阅读:

见第三节:有关请求参数的更多信息包括请求参数修改响应。

1.2 控制器

JSON API的1.0版引入了模块化控制器系统。这允许开发人员灵活的添加API的功能和给用户更多方法启用控制。

核心控制器

之前大多数的1.0可用方法已经被移到核心控制器。除了 submitcomment 和 createpost ,它们分别是现在可用的响应控制器和文章控制器。

核心控制器是唯一一个默认的可用控制器。其他的所有功能必须从JSON API的设置页面中启用(设置在WP后台的管理菜单中)。

指定控制器

这里有几个方法指定一定控制器,取决与你如何调用API:

  • http://www.example.org/?json=getrecentposts (核心控制器是隐含的,方法是getrecentposts)
  • http://www.example.org/api/info/ (核心控制器是隐含的)
  • http://www.example.org/api/core/getcategoryposts/ (核心控制器也可以显式指定)
  • http://www.example.org/?json=respond.submit_comment (响应控制器,submit_comment 方法)

旧版本兼容

JSON API保留了1.0版本以前的支持。例如,如果你调用该方法不指定Posts 控制器,它将自己选择,而不是核心。

可用控制器

当前版本包含了三个控制器:核心、文章和响应。鼓励开发者建议或者提出其他的控制器。

进一步阅读:

见第2节:可用控制器和完整请求方式参考。有关使用新的控制器扩展JSON API文档见5.2:开发JSON API控制器。

1.3 Responses

对于JSON API的标准响应,格式是JSON。

下面是一个来自 http://localhost/wordpress/?json=1 示例响应,它是默认的WP安装信息:

{
  "status": "ok",
  "count": 1,
  "count_total": 1,
  "pages": 1,
  "posts": [
    {
      "id": 1,
      "type": "post",
      "slug": "hello-world",
      "url": "http:\/\/localhost\/wordpress\/?p=1",
      "title": "Hello world!",
      "title_plain": "Hello world!",
      "content": "<p>Welcome to WordPress. This is your first post. Edit or delete it, then start blogging!<\/p>\n",
      "excerpt": "Welcome to WordPress. This is your first post. Edit or delete it, then start blogging!\n",
      "date": "2009-11-11 12:50:19",
      "modified": "2009-11-11 12:50:19",
      "categories": [],
      "tags": [],
      "author": {
        "id": 1,
        "slug": "admin",
        "name": "admin",
        "first_name": "",
        "last_name": "",
        "nickname": "",
        "url": "",
        "description": ""
      },
      "comments": [
        {
          "id": 1,
          "name": "Mr WordPress",
          "url": "http:\/\/wordpress.org\/",
          "date": "2009-11-11 12:50:19",
          "content": "<p>Hi, this is a comment.<br \/>To delete a comment, just log in and view the post's comments. There you will have the option to edit or delete them.<\/p>\n",
          "parent": 0
        }
      ],
      "comment_count": 1,
      "comment_status": "open"
    }
  ]
}

2.请求方法

请求方法可以从以下控制器得到:

  • 核心控制器:基本内省方法
  • 文章控制器:文章数据处理方法
  • 响应控制器:评论/引用提交方法
  • 桌面部件控制器:检索侧边栏小部件方法

2.1 核心控制方法

核心控制器提供了一套基本完成的从WordPress的检索内容的内省方法。

方法:info

返回关于JSON API的相关信息。

可选参数

  • controller:返回一个指定控制器的详细信息。

普通响应:

{
  "status": "ok",
  "json_api_version": "1.0",
  "controllers": [
    "core"
  ]
}

指定控制器为核心的响应:

{
  "status": "ok",
  "name": "Core",
  "description": "Basic introspection methods",
  "methods": [
    ...
  ]
}

方法:get_recent_posts

返回一个最近文章的集合。

你可以调用这些:

  • 通过设置JSON为一个非空值(即json=1)来从WP主页获取;
  • 通过设置json=get_recent_posts从任何页面获取。

可选参数

  • count - 决定返回多少数量的最近文章,默认为10;
  • page - 返回一个结果中的指定页面号;
  • post_type - 用于检索自定义文章类型。

响应:

{
  "status": "ok",
  "count": 10,
  "count_total": 79,
  "pages": 7,
  "posts": [
    { ... },
    { ... },
    ...
  ]
}

方法:get_posts

返回根据WP的WP_Query参数获取的文章,默认的参数是ignore_sticky_posts=1,它可以被覆盖。

可选参数

  • count - 决定返回多少数量的最近文章,默认为10;
  • page - 返回一个结果中的指定页面号;
  • post_type - 用于检索自定义文章类型。

进一步阅读

查看WP_Query文档对于支持参数的完整列表,目前post_status被忽略。

响应:

{
  "status": "ok",
  "count": 1,
  "posts": [
    { ... }
  ]
}

方法:get_post

返回一个简单的文章对象

下面其中一个是必需的

  • 在一个文章URL中隐式调用JSON API,也就是(?json=1);
  • id / post_id - 设置文章ID;
  • slug / post_slug - 设置文章的URL的slug。

slug是指wordpress在启用了伪静态后,你的文章(post)与页面(page)、标签(tag)、分类(Category)在访问的时候显示在浏览器地址栏上域名后面的地址。

可选参数

  • post_type - 用于检索自定义文章类型。

响应:

{
  "status": "ok",
  "post": { ... }
}

方法:get_page

返回一个简单的页面对象

下面其中一个是必需的

  • 在一个文章URL中隐式调用JSON API,也就是(?json=1);
  • id / post_id :设置文章ID;
  • slug / post_slug : 设置文章的URL的slug。

可选参数

  • children - 设置一个非空值来包括子页面的递归层次结构;
  • post_type - 用于检索自定义文章类型。

响应:

{
  "status": "ok",
  "page": { ... }
}

方法:get_date_posts

返回一个指定日期(年、月、日)归档的文章或者页面集合。

下面其中一个是必需的

  • 日期归档页面上隐含调用JSON API(即?JSON=1);
  • date - 设置一个日期格式比如 YYYY、YYYY-MM、YYYY-MM-DD(非数字字符会从变量中剥离,所以YYYYMMDD、YYYY/MM/DD也是有效的)

可选参数

  • count - 决定返回多少数量的最近文章,默认为10;
  • page - 返回一个结果中的指定页面号;
  • post_type - 用于检索自定义文章类型。

响应:

{
  "status": "ok",
  "count": 10,
  "count_total": 79,
  "pages": 7,
  "posts": [
    { ... },
    { ... },
    ...
  ]
}

方法:get_category_posts

返回一个指定分类的文章或者页面集合。

下面其中一个是必需的

  • 类别档案页面上隐含调用JSON API(即?JSON=1)
  • id or category_id - 设置分类ID
  • slug or category_slug - 设置分类URL的slug

可选参数

  • count - 决定返回多少数量的最近文章,默认为10;
  • page - 返回一个结果中的指定页面号;
  • post_type - 用于检索自定义文章类型。

响应:

{
  "status": "ok",
  "count": 10,
  "count_total": 79,
  "pages": 7,
  "category": { ... }
  "posts": [
    { ... },
    { ... },
    ...
  ]
}

方法:get_tag_posts

返回一个指定标签的文章或者页面集合。

下面其中一个是必需的

  • 类别档案页面上隐含调用JSON API(即?JSON=1)
  • id or tag_id - 设置标签ID
  • slug or tag_slug - 设置标签URL的slug

可选参数

  • count - 决定返回多少数量的最近文章,默认为10;
  • page - 返回一个结果中的指定页面号;
  • post_type - 用于检索自定义文章类型。

响应:

{
  "status": "ok",
  "count": 10,
  "count_total": 79,
  "pages": 7,
  "tag": { ... }
  "posts": [
    { ... },
    { ... },
    ...
  ]
}

方法:get_author_posts

返回一个指定作者的文章或页面集合。

下面其中一个是必需的

  • 类别档案页面上隐含调用JSON API(即?JSON=1)
  • id or author_id - 设置作者ID
  • slug or author_slug - 设置作者URL的slug

可选参数

  • count - 决定返回多少数量的最近文章,默认为10;
  • page - 返回一个结果中的指定页面号;
  • post_type - 用于检索自定义文章类型。

响应:

{
  "status": "ok",
  "count": 10,
  "count_total": 79,
  "pages": 7,
  "author": { ... }
  "posts": [
    { ... },
    { ... },
    ...
  ]
}

方法:get_search_results

返回文章/页面响应搜索查询的集合。

下面其中一个是必需的

  • 一个搜索结果页上隐含调用JSON API(即?JSON=1)
  • search - 设置希望查询的内容

可选参数

  • count - 决定返回多少数量的最近文章,默认为10;
  • page - 返回一个结果中的指定页面号;
  • post_type - 用于检索自定义文章类型。

响应:

{
  "status": "ok",
  "count": 10,
  "count_total": 79,
  "pages": 7,
  "posts": [
    { ... },
    { ... },
    ...
  ]
}

方法:get_date_index

返回日期页面的永久链接的集合和树状的归档文件。

响应:

{
  "status": "ok",
  "permalinks": [
    "...",
    "...",
    "..."
  ],
  "tree": {
    "2009": {
      "09": 17,
      "10": 20,
      "11": 7
    }
  }
}

方法:get_category_index

返回有效的分类集合

可选参数

  • parent - 返回父类Id的直接子类

响应:

{
  "status": "ok",
  "count": 3,
  "categories": [
    { ... },
    { ... },
    { ... }
  ]
}

方法:get_tag_index

返回有效的标签集合

响应:

{
  "status": "ok",
  "count": 3
  "tags": [
    { ... },
    { ... },
    { ... }
  ]
}

方法:get_author_index

返回有效的博客作者

响应:

{
  "status": "ok",
  "count": 3,
  "authors": [
    { ... },
    { ... },
    { ... }
  ]
}

方法:get_page_index

返回一个页面文章的层次树。

响应:

{
  "status": "ok",
  "pages": [
    { ... },
    { ... },
    { ... }
  ]
}

方法:get_nonce

返回一个WordPress的现时价值,调用一些所需的数据操作方法。

必需参数

  • controller - 该方法的JSON API控制器将用于该随机数
  • method-要调用的方法(目前create_post是得到随机数的唯一方法)

响应:

{
  "status": "ok",
  "controller": "posts",
  "method": "create_post",
  "nonce": "cefe01efd4"
}

进一步阅读:

要了解更多关于随机数如何在WordPress的使用,请看Mark Jaquith's article on the subject

2.2 文章控制器方法

方法:create_post

新建一篇文章

必需参数

  • nonce - 可从getnonce方法得到可用的(调用变量controller=posts和method=createpost)

可选参数

  • status - 设置后的状态("草稿"或"发布"),默认是"草稿";
  • title - 文章标题;
  • content - 文章内容;
  • author - 这篇文章的作者(登录名),默认为当前登录用户;
  • categories - 以逗号分隔的分类列表(固定URL);
  • tags - 一个以逗号分隔的标签列表(固定URL)。

注意:包括上传附件的 attachment 字段,将保存在您的新文章。

方法:update_post

更新一篇文章。

必需参数

  • nonce - 可从getnonce方法得到可用的(调用变量controller=posts和method=createpost)

下面其中一个是必需的

  • id / post_id :设置文章ID;
  • slug / post_slug : 设置文章的URL的slug。

可选参数

  • status - 设置后的状态("草稿"或"发布"),默认是"草稿";
  • title - 文章标题;
  • content - 文章内容;
  • author - 这篇文章的作者(登录名),默认为当前登录用户;
  • categories - 以逗号分隔的分类列表(固定URL);
  • tags - 一个以逗号分隔的标签列表(固定URL)。

注意:包括上传附件的 attachment 字段,将保存在您的新文章。

方法:delete_post

删除一篇文章。

必需参数

  • nonce - 可从getnonce方法得到可用的(调用变量controller=posts和method=createpost)

下面其中一个是必需的

  • id / post_id :设置文章ID;
  • slug / post_slug : 设置文章的URL的slug。

2.3 响应控制器方法

方法:submit_comment

提交一个评论到WP文章。

必需参数

  • post_id - 文章id
  • name - 评论者的名字
  • email - 评论者的电子邮件地址
  • content - 评论内容

可选参数

  • redirect - 重定向而不是返回JSON对象
  • redirect_ok - 重定向到一个特定的URL时的状态值 ok
  • redirect_error - 重定向到一个特定的URL时的状态值 error
  • redirect_pending - 重定向到一个特定的URL时的状态值 pending

自定义状态值

  • pending - 如果评论是提交待审核的时候指定

2.4 小部件控制器方法

方法:get_sidebar

检索分配到侧边栏的小工具。

必需参数

  • sidebar_id - 侧边栏的名称或编号检索。

3、请求参数

API请求可以通过指定下列参数之一作为URL查询变量。

举例:

  • 调试回应: http://www.example.org/api/getpageindex/?dev=1
  • 控件样式JSONP输出: http://www.example.org/api/getrecentposts/?callback=show_postswidget&readmore=More&count=3
  • 重定向错误: http://www.example.org/api/posts/createpost/?callbackerror=http%3A%2F%2Fwww.example.org%2Fhelp.html

3.1 输出修饰参数

下面的参数修饰你从API返回什么样的结果。重定向响应样式用于数据处理方法中。

  • 设置 callback JavaScript函数名将触发JSONP式的回调。
  • 设置 redirect 到URL会导致用户的浏览器重定向到指定的、追加状态值到查询变量中的URL(见下面一节响应对象对状态值的解释)。
  • 设置 redirect_[status] 允许您根据不同的status值控制浏览器重定向。
  • 设置 dev 一个非空值增加了text/plain可读性和空白响应。
  • 误差被抑制,除非dev被设为非空值。
  • 设置 jsonencodeoptions 将让您指定整数位掩码来修改PHP的json_encode(注:此选项仅在PHP版本公认5.3+)
  • 设置 jsonunescapedunicode 将其转义等效替代的Unicode转义字符。
  • 省略所有上述参数将导致一个标准JSON响应。

3.2 内容修饰参数

这些参数可以修饰所有内省的方法:

  • date_format-更改日期值的格式。使用相同的语法是PHP的 data() 函数。默认值是Y-m-d H:i:s。
  • read_more - 改变"阅读更多"在文章内容中的链接文字。
  • include - 指定文章哪个数据字段。要求用逗号分隔后的字段列表。所有的字段不能为空。
  • exclude - 指定排除文章哪个数据字段。要求用逗号分隔后的字段列表。
  • custom_fields - 包括文章自定义的字段。要求逗号分隔的自定义字段的键列表。
  • author_meta - 包括额外的元数据的作者。应该是一个逗号分隔的元数据字段列表。
  • count - 控制文章数目,包括(默认为由WordPress指定的号码)
  • order - 控制文章结果的顺序(“DESC”或“ASC”)。默认值是'DESC'。
  • order_by - 控制哪些字段结果需要排序。要求是下列值之一:
    • author
    • date (默认值)
    • title
    • modified
    • menu_order (只在页面有作用)
    • parent
    • ID
    • rand
    • metavalue(metakey也必须设置)
    • none
    • comment_count
  • metakey,metavalue,meta_compare-检索基于自定义字段中的键或值的文章(或页面)。

3.3 使用 include/exclude/redirects

关于 include/exclude参数

默认情况下你会得到包括每个文章对象的所有值。指定列表中的 include 值可以让对象过滤掉一些没有的值。指定列表的 exclude 可以让文章对象包含除去你的列表中的字段的所有值。比如查询 exclude=comments 会包含除去comments的所有值。

关于redirects参数

重定向响应样式作用在于当你需要用户在浏览器发出请求而不是使用像cURL那样的代理请求。设置一个 redirect 参数会让用户浏览器重新想到指定的URL而不是返回一个JSON对象,由此产生的状态值是作为一个额外的查询变量。

例如用redicect调用API的方法设置为http://www.example.com/foo将导致重定向到下列之一:

  • http://www.example.com/foo?status=ok
  • http://www.example.com/foo?status=error
  • 您还可以设置不同的网址,以不同方式处理状态值。您可以设置redirectok为http://www.example.com/handleok,并redirecterror为http://www.example.com/handleerror,为了有更多的调整控制方法的结果。

4、响应对象

本节介绍您可以从WordPress的检索数据对象和可选的URL重定向。

状态值

所有的JSON API请求结果中都有状态值。这两个基本状态值ok和error。附加状态值可用于某些方法(如pending在的情况下,submit_comment方法)。这里自定义状态值的API方法在文档中包含自定义状态值的这一节。

命名兼容性

熟悉WordPress开发可能会注意到性能和参数的许多名字已被更改。这是一个风格上的选择,打算提供更多的清晰度和一致性的接口。

4.1 文章响应对象

  • id - Integer
  • type - String (例如文章或者页面)
  • slug - String
  • url - String
  • title - String
  • title_plain - String
  • content - String (通过修改 read_more参数)
  • excerpt - String
  • date - String (通过修改date_format参数)
  • modified - String (通过修改date_format参数)
  • categories - 分类对象集合
  • tags - 标签对象集合
  • author - 作者对象
  • comments - 评论对象集合
  • attachments - 附件对象集合
  • comment_count - Integer
  • comment_status - String ("open" 或者 "closed")
  • thumbnail - String (只在指定一个缩略图)
  • customfields - Object (通过设置包括customfields参数用逗号分隔的自定义字段名称列表)
  • taxonomy_(taxonomy) - 自定义分类对象的集合 (这些类似分类或标签响应对象,依赖于分类是否是层级的)

注意:该thumbnail属性返回URL通过可选参数thumbnail_size指定的图片尺寸。默认情况下,这将使用 thumbnail 或 post-thumbnail 大小,取决于你的WordPress版本。

4.2. 分类响应对象

  • id - Integer
  • slug - String
  • title - String
  • description - String
  • parent - Integer
  • post_count - Integer

4.3. 标签响应对象

  • id - Integer
  • slug - String
  • title - String
  • description - String
  • post_count - Integer

4.4. 作者响应对象

  • id - Integer
  • slug - String
  • name - String
  • first_name - String
  • last_name - String
  • nickname - String
  • url - String
  • description - String

**注意:您可以通过设置包括其他值author_meta参数,以逗号分隔的元数据字段列表。 **

4.5. 评论响应对象

  • id - Integer
  • name - String
  • url - String
  • date - String
  • content - String
  • parent - Integer
  • author - Object (只在评论作者已经注册或登录)

4.6. 附件响应对象

  • id - Integer
  • url - String
  • slug - String
  • title - String
  • description - String
  • caption - String
  • parent - Integer
  • mime_type - String
  • images - 有值的对象包括thumbnail,medium,large,full,其中每一个具有url,width和height的对象,只在附件是图片的时候起作用。

声明:XiaRui's Zone|版权所有,违者必究|如未注明,均为原创|本网站采用BY-NC-SA协议进行授权

转载:转载请注明原文链接 - 【译】JSON API for WP 文档翻译


在能驾驭的领域 做个自由的行者