wp-api / docs-v2

Documentation for version 2 of the API

These files comprise v2.wp-api.org. The endpoint documentation is programmatically, but manually, generated from the API.

Installation

You should have Ruby and gem installed.

Install Jekyll

Install bundler

Install gem dependencies

bundle install

Setup

Build the endpoint documentation:

ruby regenerate.rb

Run the website locally, and recompile files on change

bundle exec jekyll serve --watch

Open http://0.0.0.0:4000 in your browser to see the site

Notes

Styles use of Foundation v 5.5.3

docs-v2's Issues

Document the search-replace --regex flag

There's currently no documentation on how the regex flag in the search-replace module functions, I noticed a bit of confusion on what it considers the replace element of the pattern, and what should be included (do you need the / wrappers to give flags to the pattern for example).

A documented block for this along with an example would be fantastic.

Document best practices for adding fields to response (register_rest_field/register_meta)

We should communicate best practices for adding fields to responses.

Example requests:

• Featured image in /posts as link instead of ID

Document uploading an attachment

We should document the different types of requests you can make to upload an attachment.

Front page search param is incorrect

GET /wp-json/wp/v2/posts?s=awesome is incorrect, and the search query will be ignored.

GET /wp-json/wp/v2/posts?filter[s]=awesome is correct.

Cannot regenerate the documentation

Manually regenerating the documentation via the phake script doesn’t work now that the schema endpoints are options requests. Broken since WP-API/WP-API#1415

MIgration with old version

I need to support the old version urls because of backward compatibility (I use this API on android mobile application) and I want to add new features exist on v2 of wp-api to my new versions
but when I download v2 I can not access routes and I got error with code json_no_route
can you suggest a solution? or there is a way to change v2 api url from wp-json/wp/v2/ to something else

Automagically add relative link marker

Github has a nice relative link marker on documentation:

We should add something similar to our documentation:

Mention DELETE philosophy: return the original resource

From WP-API/WP-API#1224

Cloud you add some plugins to "Compatible Plugins on the WordPress.org Plugin Repository"?

I made some Plugin that using WP REST API(v2).
Cloud you add following plugins to "Compatible Plugins on the WordPress.org Plugin Repository"?

WP API Shortcodes

Simple Shortcode Plugin to get WordPress data from WP REST API(Version2)
https://wordpress.org/plugins/wpapi-shortcode-and-widgets/

Rest API Widgets

This is simple Widget Plugin using WP REST API. You can use following Widgets.

• Comment form if comment is closed, this widget is hidden.
• Comment List if comment is closed, this widget is hidden.
• Post List Default: recentry 10 posts.
  https://wordpress.org/plugins/rest-api-widgets/

thanks.

Plugin: Rest API Filter Fields

Could you please add my plugin to the list of compatible plugins?

• Rest filter fields on Wordpress.org/plugins
• Rest filter fields on Github
• Blog post about it

This plugin enables users to downsize the api response to only the needed fields (by adding a query parameter), and makes it really easy to use wordpress on a mobile app, where you want to watch the transmitted data.

Prose documentation is pushed over way too far

Not sure how this happened, should be centred instead.

Describe our different magic parameters

_embed et all deserve some special mention.

Document WP-API v2 clients

Let's put all of the WP-API v2.0 clients on a page in the docs

Use absolute URLs for pages

While the single page effect is nice, it makes it painful to add links and negatively impacts SEO. Let's switch to absolute URLs. It's a static website, so pageloads should be fast enough.

Document nonce-based authentication

We have OAuth1 and Basic authentication documented. We should have some mention of the standard authentication cookies + nonce too that we can point to.

From WP-API/WP-API#1311

Translation

Have any translation plan? How to contribute translating docs-vs of WP-API?

Add a "What Is A REST API?"

It's unsafe to assume that everyone reading the docs/ using the WordPress REST API knows what a REST API is. Hard to explain what the WordPress REST API is if you can't assume knowledge of REST APIs.

Docs should have a "What Is A REST API?" section that explains what such a thing is, in general and in the context of WordPress. I should write this. If someone else does first, +5 you.

Modifying Responses: Two example functions are declared public outside of object context

http://v2.wp-api.org/extending/modifying/

I will fix.

getting the posts without authentication also

Hi, just i set up my own wordpress site and wp-api v2 beta installed, im getting the users list when i go to this url myurl/wp-josn/wp/v2/users im getting the list as json im wondering this doesn't require an authentication like access token like that. I have also installed Oauth server plugin but no use of it.

Document philosophy for adding actions and filters

To have some consistency as to where we have actions and filters in the codebase, we should have a documented philosophy for when we add actions and filters (and when we don't).

Action and filter reference

We should build pages for each of our actions and filters.

Mention consistency as a philosophy

Consistency is important for every API.

Simplify Sass/Remove heavy Foundation usage in docs

I think it would make contributing visual fixes and improvements to the current docs site quite a bit more accessible if we simplified the foundation usage and general over sassyness files.

For example: https://github.com/WP-API/docs-v2/blob/gh-pages/assets/styles/style.scss#L109

Add docs explaining the Schema concept

Addition of Examples & Use Cases

Create a new section (with nav) sorted by language / framework. Each page (language/framework) should have at minimum the following examples:

• GET - posts, posts with filter, custom post type
• POST - creating a new post
• UPDATE - editing a post
• DELETE - deleting a post

Will start with:

• PHP (WordPress focused)
• jQuery
• AngularJS
• BackboneJS
• ReactJS

WP_API_Settings has changed to wpApiSettings

As of 11 January the WP_API_Settings localised javascript object has changed to wpApiSettings. This should be added to the "what's changed" section in the docs. (I'd add it myself, but I'm sure someone else will know better than me.)

Thanks!

Document how to modify authentication behavior at the application level

Request from WP-API/WP-API#1635 (comment)

Meta endpoint clarifications

When we get around to adding documentation for the meta endpoints, we should mention:

1. Meta endpoints are only registered if the post type supports custom-fields. If the post type doesn't, the endpoints need to be manually registered WP-API/WP-API#1637
2. Developers would be better off to add attributes to their resource, than using meta endpoints.

Error when trying to serve documentation locally

I am getting this error when running jekyll serve:

Configuration file: /repos/wp-api/docs-v2/_config.yml
            Source: /repos/wp-api/docs-v2
       Destination: /repos/wp-api/docs-v2/_site
 Incremental build: disabled. Enable with --incremental
      Generating... 
  Dependency Error: Yikes! It looks like you don't have redcarpet or one of its dependencies installed. In order to use Jekyll as currently configured, you'll need to install this gem. The full error message from Ruby is: 'cannot load such file -- redcarpet' If you run into trouble, you can find helpful resources at http://jekyllrb.com/help/! 
  Conversion error: Jekyll::Converters::Markdown encountered an error while converting 'changes-beta-1.md':
                    redcarpet
             ERROR: YOUR SITE COULD NOT BE BUILT:
                    ------------------------------------
                    redcarpet

Versions:

• Ruby: 2.2.4p230
• jekyll: 3.0.1
• bundler: 1.11.2

Document capabilities required for endpoints

It would be nice for the documentation to mention what capabilities are required to read/write to the various endpoints. Eg, it seems no capabilities are required to create a comment but that currently isn't documented

Port over content from v1 documentation

We should port over the parts that are still relevant.

Add documentation on how to run requests internally

For server side JavaScript rendering I want to call some of the API functions in PHP code. What is the best way to do this? For example, how can I fetch all the categories

xx/wp-json/wp/v2/categories

without a cURL request, but with normal PHP code within my WordPress plugin. Thanks!

Capture magical behavior of /users/me

Users are confused why 301 redirects cause problems for whatever client they're using.

See WP-API/WP-API#1165, WP-API/WP-API#1093

Glossary for common terms

We should have a glossary for common terms (e.g. Resource, Controller, etc.) that can serve as an entry point to our documentation.

• Resource
• Controller
• HTTP client
• JSON parser
• HEAD request
• GET request
• Routes
• Endpoints
• Meta Object
• Class
• Schema

Authentication docs reference old nonce name,

Related: WP-API/WP-API#1524

OAuth example code referenced doesn't work and is outdated

On the Authentication page: http://v2.wp-api.org/guide/authentication/
Under "OAuth Authentication", an API Console: https://github.com/WP-API/api-console , is mentioned as a reference.

After spending a couple days trying to get it working, it became obvious to me that it wasn't designed for the v2 API, hasn't been updated in a year, and tries to do client-side authentication over OAuth sending a client key and secret in the clear from a JavaScript client.

I'd propose removing this reference link altogether as I don't feel it is a good starting place for people to learn how to use OAuth with the v2 API, and it teaches some really insecure practices that we should hope no one actually follows in their own application development.

Build endpoint documentation dynamically based on scheme

That's the grand idea, at least.

WP-CLI uses Phake to turn PHPdoc into static markdown files. It works pretty well — we could do something similar.

Add documentation on discovery

Got this written, leaving here so I remember to push in the morning.

Document how registration arguments for an endpoint can be modified

Because our registration parameters are used for validation and sanitization, we should have some documentation on how plugins are expected to modify them.

Document API activation

Document how to make sure API is active using constant or other variable

Additional 3 plugins which utilizes the WP REST API v2

Hi,
I created 3 plugins which utilizes the WP REST API v2:
WP REST API - Pure Taxonomies
WP REST API - All Terms
WP REST API - Post Type Taxonomies

You can find all my rest-api plugins using "andrew-magik-rest-api" tag:
https://wordpress.org/plugins/tags/andrew-magik-rest-api

Would be nice, if you will add my plugins to the list with all other plugins from this page:
http://v2.wp-api.org/guide/plugins/

Thanks in advance!

Namespaces: What are they and best practices.

This is covered lightly in extending section, but an explanation of what are namespaces in the context of the WordPress REST API would be helpful.

Should include:

• Why namespaces
• Versioning
• Best practices
• The special wp/ namespace (related: https://core.trac.wordpress.org/ticket/34305)
• Namespace routes

Extending WP_REST_Posts_Controller

Hello

Can someone give me a link to a tutorial which deal with extending WP_REST_Posts_Controller

I need more control on the data return to my mobile app and add some other functions. The standard class doesn't.

Thanks a lot

Regards
Alexandre

Create a new post using REST API.

Hi I try to make a app using AngualrJs and Ionic with wordpress REST API.
In this app get the data from wordpress using wordpress REST API,

Now i try to create a new post through my app using REST API.

Its Give me the errror

{"code":"rest_cannot_create","message":"Sorry, you are not allowed to create new posts.","data":{"status":401}}

I also pass the header to and convert username and password to base64(YmxvYWdZXI6czdWx0QCNAIQ==) formet

$http call $http.defaults.headers.common.Authorization = 'Basic YmxvYWdZXI6czdWx0QCNAIQ==';

Best practices for registering your own endpoints

Related to #1, we should have some over-arching best practice documentation for users to register their own endpoints.

Provide sanitize_callback example for register_rest_route

sanitize_callback is mentioned alongside validate_callback under Arguments but there's no example provided, which would be incredibly helpful.

Common filter hacks

We should have a place in our docs for common filter hacks, to help mitigate a bunch of support requests like this one

Create tags docs

Now that categories and tags are treated differently, we should have endpoint documentation for tags too.

Document the design decisions for our infrastructure classes

Our infrastructure classes are rich with history. Let's document why they exist, the problems they solve, and how they work:

• WP_HTTP_Response
• WP_HTTP_ResponseInterface
• WP_JSON_DateTime
• WP_JSON_Controller
• WP_JSON_Request
• WP_JSON_Response
• WP_JSON_Server

Needs info about Wordpress version to use

The download link on the home page says it needs Wordpress 4.3+, but no info on how to get that build.