Documentation of the KickPress plugin.

API Query String Parameters

Description

The KickPress API makes use of the URL “permalink” structure to pass parameters to the KickPress plugin. Any parameter pairs passed after “/api/” are assumed to belong to the KickPress API permalink structure, any parameters passed in the URL before the URL fragment “/api/” are assumed to belong to the WordPress permalink structure. KickPress looks for the “/api/” string fragment in the URL to determine if there is an API request being executed. Whatever parameters pairs are found in the URL after the “/api/” string fragment are rewritten into query string parameters by KickPress before they reach WorkPress.

So, the API URL requests passed through the URL permalinks are translated by the KickPress plugin, here are some examples:
Request: kickpress.org/documentation/api/add
Result: kickpress.org/documentation/?action=add

Request: kickpress.org/documentation/api-authentication/api/edit/
Result: kickpress.org/documentation/api-authentication/?action=edit

Request: kickpress.org/documentation/api/sort_direction/DESC/sort_field/post_title/
Result: kickpress.org/documentation/?sort_direction=DESC&sort_field=post_title

Request: kickpress.org/documentation/api/sort_direction/DESC/sort_field/post_date/posts_per_page/2/
Result: kickpress.org/documentation/?sort_direction=DESC&sort_field=post_date&posts_per_page=2

Parameters

API Actions

API Actions are operations that take place on the web server and perform changes to WordPress content, such as updating and deleting posts, or applying tags and categories. Each action query takes one of two forms: simple or parameterized. Simple action queries are single action names to be executed on the selected post or collection, as determined by the WP portion of the permalink. Parameterized action queries are also action names with an extra parameter that modifies how the action is to be executed (which taxonomy to apply terms from, for instance). Formatted action queries will look something like the following:

Simple: /post_type/post_name/api/action_name
Parameterized: /post_type/post_name/api/action_name[param]

Built-in API Actions
The following actions are built into the API base class and are valid by default for all post types:

save
Either inserts or updates the post specified by the post slug in the WP permalink. Post content is sent in the HTTP request

delete
Deletes the post specified by the post slug in the WP permalink.

export

add-terms
Adds terms to the post specified by the post slug in the WP permalink. Taxonomy must be specified as action parameter. Terms are passed as slugs following action call.

remove-terms
Removes terms from the post specified by the post slug in the WP permalink. Taxonomy must be specified as action parameter. Terms are passed as slugs following action call.

toggle-term
Toggles terms on the post specified by the post slug in the WP permalink. Taxonomy must be specified as the action parameter. Terms are passed as slugs following action call.

add-bookmark
Adds a bookmark on the post specified by the post slug in the WP permalink for the currently logged-in user.

remove-bookmark
Removes the bookmark on the post specified by the post slug in the WP permalink for the currently logged-in user.

toggle-bookmark
Toggles the bookmark on the post specified by the post slug in the WP permalink for the currently logged-in user.

add-note
Adds a note to the post specified by the post slug in the WP permalink for the currently logged-in user. Note content is passed in the HTTP request.

update-note
Adds a note for the currently logged-in user. The note ID must be passed as the action parameter. Note content is passed in the HTTP request.

delete-note
Deletes a note for the currently logged-in user. The note ID must be passed as the action parameter.

API Views

API views are custom templates that render the post(s) requested in the WP permalink for alternative use cases, such as an input form or data table. Formatted view queries will look something like the following:

Collection: /post_type/api/view_name
Single Post: /post_type/post_name/api/view_name

Form View
The form view is a special case. All other custom views are loaded from their corresponding theme templates. In the case of form, the view is generated programmatically according to the post type’s custom fields. If a post slug is specified, the form will be populated with the corresponding post’s content.

API Filters

API filters add specific criteria to a query. Each filter takes one of two forms: simple or parameterized. Simple filters are basic key-value pairs where the key is the name of the filter and the value is a string to be matched against the post. Parameterized filters are also key-value pairs with an extra parameter that specifies how the filter is to be applied (which taxonomy to match terms against, for instance). Formatted filters will look something like the following:

Simple: /post_type/api/filter_name/filter_data
Parameterized: /post_type/api/filter_name[param]/filter_data

Filters can be combined in a single url to produce very specific result sets. A parameterized filter can even be used multiple times, provided each instance of the filter uses a different parameter value.

search
This filter is a typical keyword search. Keywords are matched in the posts’ title, content, and custom fields. Posts with matches for ANY keyword across ANY field are selected. (This is different from WP search where only posts with matches for ALL keywords across ANY fields are selected.) Keywords can be specified by url-encoded whitespace or a comma-separated list.

Examples
/documents/api/search/some%20search%20keywords
/documents/api/search/some+search+keywords
/documents/api/search/some,search,keywords

author
This filter will select all posts of the given post type written by the specified author(s). Multiple authors can be specified by a comma-separated list.

Examples
/documents/api/author/john-smith
/documents/api/author/jane-doe
/documents/api/author/john-smith,jane-doe

date[min|max]
This filter will select all posts published after the MIN date, before the MAX date, or between the MIN and MAX dates, according to which dates are specified. All comparisons are inclusive, so posts published on a given date are selected. Values passed to this filter must be formatted date strings (YYYY-MM-DD).

Examples
/documents/api/date[min]/2001-09-11
/documents/api/date[max]/2012-04-17
/documents/api/date[min]/2001-09-11/date[max]/2012-04-17

filter[field]
This filter will select all posts with the specified field (either standard or custom) exactly matching one of the specified values. Multiple values can be specified by a comma-separated list.

Examples
/documents/api/filter[vendor]/abc-supplies
/documents/api/filter[vendor]/xyz-services
/documents/api/filter[vendor]/abc-supplies,xyz-services

term[taxonomy]
This filter will select all posts belonging to the given set of taxonomy terms. Multiple terms for a given taxonomy can be specified as a comma-separated list.

Examples
/documents/api/term[category]/business-trips
/documents/api/term[category]/quarterly-reports
/documents/api/term[category]/business-trips,quarterly-reports

first_letter
This filter will select all posts whose admin-specified alphabar field begins with the specified character. This filter can only receive a single value. Special cases are made for the keyword “0-9” which matches all digits and the keyword “all” which matches all characters. The alphabar field is chosen from the admin panel for the specified post type.

Examples
/documents/api/first_letter/0-9
/documents/api/first_letter/B
/documents/api/first_letter/all

API Sorting and Pagination

sort[field]
This parameter will sort the selected posts by the specified field and ordering. Nested sorting can be done using multiple sorts.

Examples
/books/api/sort[date]/desc
/books/api/sort[title]/asc
/books/api/sort[date]/desc/sort[title]/asc

posts_per_page
This parameter will change the number of posts displayed on each page of an archive view. This will change the number of pages in the archive accordingly.

Examples
/events/api/posts_per_page/5
/events/api/posts_per_page/25

Comments are closed.