The document provides an overview of the WordPress REST API. It begins by defining what an API is and explaining that the WordPress REST API exposes WordPress data through HTTP requests that return JSON responses. It discusses how the API makes WordPress more flexible and extensible by allowing developers to build applications that interact with WordPress sites. The document then covers some key aspects of the WordPress REST API like routes, endpoints, authentication, and examples of how it is being used.
1. WP-AP, Why?
Review the WP REST API &
see What it people are making with it
Slides available: https://circlecube.com/does-wordpress/
WordCamp Wilmington - 23 September 2017
2. Introductions
Evan Mullins
Lead Web Developer at
Brown Bag Marketing
@circlecube
circlecube.com
WordPress user since 2006
Full-time web developer since 2007
3.
4. API
An application programming interface (API) is a set of
subroutine definitions, protocols, and tools for building software and applications. A
good API makes it easier to develop a program by providing all the building blocks,
which are then put together by the programmer.
An API is best thought of as a contract provided by one piece of software to another.
7. REpresentational State Transfer
It describes how one system can communicate state with another.
One example would be the state of a product (and properties) represented as JSON.
REST
8. JSON
JavaScript Object Notation is a lightweight data-interchange format.
It is easy for humans to read and write. It is easy for machines to parse and generate. It
is a text format that is completely language independent but uses conventions that are
familiar to programmers. These properties make JSON an ideal data-interchange
language.
JSON is built on two structures:
● A collection of name/value pairs. (object).
● An ordered list of values. (array).
9.
10.
11. The future of WordPress will use JavaScript-driven
interfaces powered by the WordPress REST API. Using
JavaScript in conjunction with the REST API makes for a
great experience for both the developer and end user,
which is why every WordPress developer should have
some understanding of JavaScript.
Matt Mullenweg
13. WordPress is moving towards becoming a
fully-fledged application framework, and we need
new APIs.
This project was born to create an easy-to-use,
easy-to-understand and well-tested framework
for creating these APIs, plus creating APIs for
core.
14. This provides an easy to use REST API,
available via HTTP.
Grab your site’s data in simple JSON format,
including users, posts, taxonomies and more.
Retrieving or updating data is as simple as
sending a HTTP request.
15. Want to get your site’s posts?
Simply send a GET request to
/wp-json/wp/v2/posts
19. Get all posts with the search term “awesome”?
GET
/wp-json/wp/v2/posts?search=awesome
It’s that easy.
20. Update user with ID 4?
Send a POST request with JSON as your data to
/wp-json/wp/v2/users/4
21. The API exposes a simple yet easy interface to
WP Query, the posts API, post meta API, users
API, revisions API and many more.
Chances are, if you can do it with WordPress,
WP API will let you do it.
24. A little history
Ryan McCue started development on an API, and then proposed a WordPress JSON
REST API Project for GSOC in April 2013 (when WordPress was on version 3.5).
Having learned many lessons and going for a rebuild we arrive at Version 2.0 as a
feature plugin. The infrastructure for the API merged into core in 4.4 (Dec 2015).
25. Although the remainder of the API (the
content endpoints) was proposed for 4.5,
the merge was delayed in order to build it
out with more endpoints.
In 4.7 (December 2016), after considerable
discussion and planning, it was officially
merged into core !
Authentication and further integration
with core in an ongoing focus.
A little history
26. IT’S ALIVE!
Did you catch that?
Every WordPress website now
comes with an API layer built in!
30. The Nutshell
So in a nutshell, rather than getting your content or data via a
webpage as part of a website (php, html, css and javascript), you
can retrieve your data via the API.
You’ll get json data that is compact and fast to transfer and then
you can do endless things with it. Create an app, load it into
another website, analyze it as data…
31. That’s one small step for your website,
one giant leap for democratizing publishing.
34. Back to WordPress
The plugin/API exposes your data in JSON format in the following content types:
Posts
Pages
Media
Custom Post Types
Post Meta
Revisions
Comments
Terms
Users
35. Routes / Endpoints
Endpoints are functions available through the API and are simply urls. This can be
things like retrieving the API index, updating a post, or deleting a comment. Endpoints
perform a specific function, taking some number of parameters and return data to the
client.
A route is the “name” you use to access endpoints, used in the URL. A route can have
multiple endpoints associated with it, and which is used depends on the HTTP verb.
36. Routes / Endpoints Example
With the URL http://example.com/wp-json/wp/v2/posts/123
The “route” is wp/v2/posts/123 (the route doesn’t include wp-json because
wp-json is the base path for the API itself.)
This route has 3 endpoints:
● GET triggers a get_item method, returning the post data to the client.
● PUT triggers an update_item method, taking the data to update, and returning the
updated post data.
● DELETE triggers a delete_item method, returning the now-deleted post data to the
client.
37. GET /wp/v2/posts get list of latest posts
GET /wp/v2/posts/<id> retrieve a single post
https://2017.wilmington.wordcamp.org/wp-json/wp/v2/posts
https://2017.wilmington.wordcamp.org/wp-json/wp/v2/posts/873
GET - to read data
43. Authentication
When and why would you need this?
To POST or read private data.
Internal WordPress code (plugin/theme development) use cookies.
External code (using WP-API as a service) use oauth?
44. Authentication
If you are building a theme or a plugin and want to access
the API of the same site where the theme or plugin will be,
you’ll want to authenticate with a cookie.
Use a nonce (WordPress security token) to connect to a
local API if your theme or plugin wants to connect to the
API of the site it’s on via ajax.
45. Nonce?
A nonce is a word or expression coined for or used only once. Usually for security
purposes they are a randomly generated number used once as a token.
WordPress nonces aren't numbers, but are a hash made up of numbers and letters.
Nor are they used only once, but have a limited "lifetime" after which they expire.
WordPress's security tokens are called "nonces" despite the above noted differences
from true nonces, because they serve much the same purpose.
46. Authentication
Write a nonce in a
wp_localize_script
with wp_create_nonce
and then pass that nonce
value in your header.
52. Examples and some Under the Hood time
1. Mobile App - Content via API
2. Mobile App - Custom endpoint to API
3. WordPress Plugin - POST content to API
4. External site - GET Content via API
5. WordPress Plugin - using js client
63. Mobile App - LDS Leaders
An app will test your knowledge and teach you the Leaders of the Church of Jesus
Christ of Latter-Day Saints – powered with WordPress via
the REST API.
72. Plugin - Sitemapper
An in-house plugin at Brown Bag Marketing to quickly get up and running with
a new WordPress site in our prototyping and wireframing multisite.
Construct your sitemap and the plugin will create a new site (in the multisite
network) and via the API create new pages according to the supplied sitemap.
73.
74. Plugin Flow
1. User builds interactive sitemap.
2. Click Export button.
3. Create JSON representation of sitemap.
4. Create new multisite if necessary.
a. Using ajax since this is not yet built into the API.
5. Recursively (if necessary) add pages to site via API.
a. Need to know endpoint to submit pages.
b. Need to know parent id to assign hierarchy.
c. Use nonce for write permissions.
6. Set other options:
a. create menus (via ajax not in API yet either) to match the sitemap.
b. assign theme and other options etc.
82. External Site - Digital Dashboard
Angular web app built at
Brown Bag Marketing to
display live stats about a
bunch of sites. Connects
to sites like pingdom,
analytics etc, . The sites
are stored in WordPress
as a CPT and loaded
dynamically and it has
featured content that’s
pulled from the WP API.
85. Plugin - Revision Browser
Browse WordPress revisions on the
front-end of your website!
The REST API includes a
JavaScript/Backbone client library, which
provides an interface for the WP REST
API by providing Backbone Models and
Collections for all endpoints exposed the
API Schema.