JSON API – WordPress plugin Free download

Click to Download

JSON API

Description

JSON API allows you to retrieve and manipulate WordPress content using HTTP requests. There are three main goals:

Provide a simple, consistent external interface
Create a stable, understandable internal implementation
Enable new types of extensions for WordPress

This plugin was created at The Museum of Modern Art for the weblog Inside/Out, which is served from Ruby on Rails. Instead of reimplementing the site templates as a WordPress theme, we opted for a Rails front-end that displays content served from a WordPress back-end. JSON API provides the necessary interface for retrieving content and accepting comment submissions.

See the Other Notes section for the complete documentation.

Documentation

General concepts
1.1. Requests
1.2. Controllers
1.3. Responses
Request methods
2.1. Core controller methods
2.2. Posts controller methods
2.3. Respond controller methods
2.4. Widgets controller methods
Request arguments
3.1. Output-modifying arguments
3.2. Content-modifying arguments
3.3. Using include/exclude and redirects
Response objects
4.1. Post response object
4.2. Category response object
4.3. Tag response object
4.4. Author response object
4.5. Comment response object
4.6. Attachment response object
Extending JSON API
5.1. Plugin hooks
5.2. Developing JSON API controllers
5.3. Configuration options
Unit tests
6.1. Preparing a WordPress test site
6.2. Running the tests

1. General Concepts

1.1. Requests

Requests use a simple REST-style HTTP GET or POST. To invoke the API, include a non-empty query value for json in the URL.

JSON API operates in two modes:

Implicit mode is triggered by setting the json query var to a non-empty value on any WordPress page. The content that would normally appear on that page is returned in JSON format.
Explicit mode is triggered by setting json to a known method string. See Section 2: Request methods for a complete method listing.

Implicit mode examples:

http://www.example.org/?json=1
http://www.example.org/?p=47&json=1
http://www.example.org/tag/banana/?json=1

Explicit mode examples:

http://www.example.org/?json=get_recent_posts
http://www.example.org/?json=get_post&post_id=47
http://www.example.org/?json=get_tag_posts&tag_slug=banana

With user-friendly permalinks configured:

http://www.example.org/api/get_recent_posts/
http://www.example.org/api/get_post/?post_id=47
http://www.example.org/api/get_tag_posts/?tag_slug=banana

Further reading
See Section 3: Request arguments for more information about request arguments to modify the response.

1.2. Controllers

The 1.0 release of JSON API introduced a modular controller system. This allows developers to flexibly add features to the API and give users more control over which methods they have enabled.

The Core controller

Most of the methods available prior to version 1.0 have been moved to the Core controller. The two exceptions are submit_comment and create_post which are now available from the Respond and Posts controllers, respectively. The Core controller is the only one enabled by default. All other functionality must be enabled from the JSON API Settings page (under Settings in the WordPress admin menu).

Specifying a controller

There are a few ways of specifying a controller, depending on how you are calling the API:

http://www.example.org/?json=get_recent_posts (core controller is implied, method is get_recent_posts)
http://www.example.org/api/info/ (core controller is implied)
http://www.example.org/api/core/get_category_posts/ (core controller can also be explicitly specified)
http://www.example.org/?json=respond.submit_comment (respond controller, submit_comment method)

Legacy compatibility
JSON API retains support for its pre-1.0 methods. For example, if you invoke the method create_post without a controller specified, the Posts controller is chosen instead of Core.

Available controllers

The current release includes three controllers: Core, Posts, and Respond. Developers are encouraged to suggest or submit additional controllers.

Further reading
See Section 2: Request methods for a complete reference of available controllers and methods. For documentation on extending JSON API with new controllers see Section 5.2: Developing JSON API controllers.

1.3. Responses

The standard response format for JSON API is (as you may have guessed) JSON.

Here is an example response from http://localhost/wordpress/?json=1 called on a default WordPress installation (formatted for readability):

{
  "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"
    }
  ]
}<h3>2. Request methods</h3>

Request methods are available from the following controllers:

Core controller – basic introspection methods
Posts controller – data manipulation methods for posts
Respond controller – comment/trackback submission methods
Widgets controller – retrieve sidebar widgets

2.1. Core controller methods

The Core controller offers a mostly-complete set of introspection methods for retrieving content from WordPress.

Method: info

Returns information about JSON API.

Optional arguments

controller – returns detailed information about a specific controller

Response

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

Response with “controller=core”

{
  "status": "ok",
  "name": "Core",
  "description": "Basic introspection methods",
  "methods": [
    ...
  ]
}<h3>Method: get_recent_posts</h3>

Returns an array of recent posts. You can invoke this from the WordPress home page either by setting json to a non-empty value (i.e., json=1) or from any page by setting json=get_recent_posts.

Optional arguments

count – determines how many posts per page are returned (default value is 10)
page – return a specific page number from the results
post_type – used to retrieve custom post types

Response

{
  "status": "ok",
  "count": 10,
  "count_total": 79,
  "pages": 7,
  "posts": [
    { ... },
    { ... },
    ...
  ]
}<h3>Method: get_posts</h3>

Returns posts according to WordPress’s WP_Query parameters. The one default parameter is ignore_sticky_posts=1 (this can be overridden).

Optional arguments

count – determines how many posts per page are returned (default value is 10)
page – return a specific page number from the results
post_type – used to retrieve custom post types

Further reading
See the WP_Query documentation for a full list of supported parameters. The post_status parameter is currently ignored.

Response

{
  "status": "ok",
  "count": 1,
  "posts": [
    { ... }
  ]
}<h3>Method: get_post</h3>

Returns a single post object.

One of the following is required

Invoking the JSON API implicitly (i.e., ?json=1) on a post URL
id or post_id – set to the post’s ID
slug or post_slug – set to the post’s URL slug

Optional arguments

post_type – used to retrieve custom post types

Response

{
  "status": "ok",
  "post": { ... }
}<h3>Method: get_page</h3>

Returns a single page object.

One of the following is required

Invoking the JSON API implicitly (i.e., ?json=1) on a page URL
id or page_id – set to the page’s ID
slug or page_slug – set to the page’s URL slug

Optional arguments

children – set to a non-empty value to include a recursive hierarchy of child pages
post_type – used to retrieve custom post types

Response

{
  "status": "ok",
  "page": { ... }
}<h3>Method: get_date_posts</h3>

Returns an array of posts/pages in a specific date archive (by day, month, or year).

One of the following is required

Invoking the JSON API implicitly (i.e., ?json=1) on a date archive page
date – set to a date in the format YYYY or YYYY-MM or YYYY-MM-DD (non-numeric characters are stripped from the var, so YYYYMMDD or YYYY/MM/DD are also valid)

Optional arguments

count – determines how many posts per page are returned (default value is 10)
page – return a specific page number from the results
post_type – used to retrieve custom post types

Response

{
  "status": "ok",
  "count": 10,
  "count_total": 79,
  "pages": 7,
  "posts": [
    { ... },
    { ... },
    ...
  ]
}<h3>Method: get_category_posts</h3>

Returns an array of posts/pages in a specific category.

One of the following is required

Invoking the JSON API implicitly (i.e., ?json=1) on a category archive page
id or category_id – set to the category’s ID
slug or category_slug – set to the category’s URL slug

Optional arguments

count – determines how many posts per page are returned (default value is 10)
page – return a specific page number from the results
post_type – used to retrieve custom post types

Response

{
  "status": "ok",
  "count": 10,
  "count_total": 79,
  "pages": 7,
  "category": { ... }
  "posts": [
    { ... },
    { ... },
    ...
  ]
}<h3>Method: get_tag_posts</h3>

Returns an array of posts/pages with a specific tag.

One of the following is required

Invoking the JSON API implicitly (i.e., ?json=1) on a tag archive page
id or tag_id – set to the tag’s ID
slug or tag_slug – set to the tag’s URL slug

Optional arguments

count – determines how many posts per page are returned (default value is 10)
page – return a specific page number from the results
post_type – used to retrieve custom post types

Response

{
  "status": "ok",
  "count": 10,
  "count_total": 79,
  "pages": 7,
  "tag": { ... }
  "posts": [
    { ... },
    { ... },
    ...
  ]
}<h3>Method: get_author_posts</h3>

Returns an array of posts/pages written by a specific author.

One of the following is required

Invoking the JSON API implicitly (i.e., ?json=1) on an author archive page
id or author_id – set to the author’s ID
slug or author_slug – set to the author’s URL slug

Optional arguments

count – determines how many posts per page are returned (default value is 10)
page – return a specific page number from the results
post_type – used to retrieve custom post types

Response

{
  "status": "ok",
  "count": 10,
  "count_total": 79,
  "pages": 7,
  "author": { ... }
  "posts": [
    { ... },
    { ... },
    ...
  ]
}<h3>Method: get_search_results</h3>

Returns an array of posts/pages in response to a search query.

One of the following is required

Invoking the JSON API implicitly (i.e., ?json=1) on a search results page
search – set to the desired search query

Optional arguments

count – determines how many posts per page are returned (default value is 10)
page – return a specific page number from the results
post_type – used to retrieve custom post types

Response

{
  "status": "ok",
  "count": 10,
  "count_total": 79,
  "pages": 7,
  "posts": [
    { ... },
    { ... },
    ...
  ]
}<h3>Method: get_date_index</h3>

Returns both an array of date page permalinks and a tree structure representation of the archive.

Response

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

Note: the tree is arranged by response.tree.[year].[month].[number of posts].

Method: get_category_index

Returns an array of active categories.

Optional argument

parent – returns categories that are direct children of the parent ID

Response

{
  "status": "ok",
  "count": 3,
  "categories": [
    { ... },
    { ... },
    { ... }
  ]
}<h3>Method: get_tag_index</h3>

Returns an array of active tags.

Response

{
  "status": "ok",
  "count": 3
  "tags": [
    { ... },
    { ... },
    { ... }
  ]
}<h3>Method: get_author_index</h3>

Returns an array of active blog authors.

Response

{
  "status": "ok",
  "count": 3,
  "authors": [
    { ... },
    { ... },
    { ... }
  ]
}<h3>Method: get_page_index</h3>

Returns a hierarchical tree of page posts.

Response

{
  "status": "ok",
  "pages": [
    { ... },
    { ... },
    { ... }
  ]
}<h3>Method: get_nonce</h3>

Returns a WordPress nonce value, required to call some data manipulation methods.

Required arguments

controller – the JSON API controller for the method you will use the nonce for
method – the method you wish to call (currently create_post is the only method that requires a nonce)

Response

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

Further reading
To learn more about how nonces are used in WordPress, see Mark Jaquith’s article on the subject.

2.2. Pages controller methods

Method: create_post

Creates a new post.

Required argument

nonce – available from the get_nonce method (call with vars controller=posts and method=create_post)

Optional arguments

status – sets the post status (“draft” or “publish”), default is “draft”
title – the post title
content – the post content
author – the post’s author (login name), default is the current logged in user
categories – a comma-separated list of categories (URL slugs)
tags – a comma-separated list of tags (URL slugs)

Note: including a file upload field called attachment will cause an attachment to be stored with your new post.

Method: update_post

Updates a post.

Required argument

nonce – available from the get_nonce method (call with vars controller=posts and method=update_post)

One of the following is required

id or post_id – set to the post’s ID
slug or post_slug – set to the post’s URL slug

Optional arguments

status – sets the post status (“draft” or “publish”), default is “draft”
title – the post title
content – the post content
author – the post’s author (login name), default is the current logged in user
categories – a comma-separated list of categories (URL slugs)
tags – a comma-separated list of tags (URL slugs)

Note: including a file upload field called attachment will cause an attachment to be stored with your post.

Method: delete_post

Deletes a post.

Required argument

nonce – available from the get_nonce method (call with vars controller=posts and method=delete_post)

One of the following is required

id or post_id – set to the post’s ID
slug or post_slug – set to the post’s URL slug

2.3. Respond controller methods

Method: submit_comment

Submits a comment to a WordPress post.

Required arguments

post_id – which post to comment on
name – the commenter’s name
email – the commenter’s email address
content – the comment content

Optional arguments

redirect – redirect instead of returning a JSON object
redirect_ok – redirect to a specific URL when the status value is ok
redirect_error – redirect to a specific URL when the status value is error
redirect_pending – redirect to a specific URL when the status value is pending

Custom status values

pending – assigned if the comment submission is pending moderation

2.4. Widgets controller methods

Method: get_sidebar

Retrieves widgets assigned to a sidebar.

Required arguments

sidebar_id – the name or number of the sidebar to retrieve

3. Request arguments

API requests can be controlled by specifying one of the following arguments as URL query vars.

Examples

Debug the response: http://www.example.org/api/get_page_index/?dev=1
Widget-style JSONP output: http://www.example.org/api/get_recent_posts/?callback=show_posts_widget&read_more=More&count=3
Redirect on error: http://www.example.org/api/posts/create_post/?callback_error=http%3A%2F%2Fwww.example.org%2Fhelp.html

3.1. Output-modifying arguments

The following arguments modify how you get results back from the API. The redirect response styles are intended for use with the data manipulation methods.

Setting callback to a JavaScript function name will trigger a JSONP-style callback.
Setting redirect to a URL will cause the user’s browser to redirect to the specified URL with a status value appended to the query vars (see the Response objects section below for an explanation of status values).
Setting redirect_[status] allows you to control the resulting browser redirection depending on the status value.
Setting dev to a non-empty value adds whitespace for readability and responds with text/plain
Errors are suppressed unless dev is set to a non-empty value
Setting json_encode_options will let you specify an integer bitmask to modify the behavior of PHP’s json_encode (Note: this option is only recognized in PHP version 5.3+)
Setting json_unescaped_unicode will replace unicode-escaped characters with their unescaped equivalents (e.g., \u00e1 becomes á)
Omitting all of the above arguments will result in a standard JSON response.

3.2. Content-modifying arguments

These arguments are available to modify all introspection methods:

date_format – Changes the format of date values. Uses the same syntax as PHP’s date() function. Default value is Y-m-d H:i:s.
read_more – Changes the ‘read more’ link text in post content.
include – Specifies which post data fields to include. Expects a comma-separated list of post fields. Leaving this empty includes all fields.
exclude – Specifies which post data fields to exclude. Expects a comma-separated list of post fields.
custom_fields – Includes values from posts’ Custom Fields. Expects a comma-separated list of custom field keys.
author_meta – Includes additional author metadata. Should be a comma-separated list of metadata fields.
count – Controls the number of posts to include (defaults to the number specified by WordPress)
order – Controls the order of post results (‘DESC’ or ‘ASC’). Default value is ‘DESC’.
order_by – Controls which field to order results by. Expects one of the following values:

author
date (default value)
title
modified
menu_order (only works with Pages)
parent
ID
rand
meta_value (meta_key must also be set)
none
comment_count

meta_key, meta_value, meta_compare – Retrieve posts (or Pages) based on a custom field key or value.

3.3. Using include/exclude and redirects

About include/exclude arguments

working fine here…
Wordpress 5.1

Leave a Reply

Your email address will not be published. Required fields are marked *