Hi everyone! I’m here today with some special news for everyone, rather than a standard release announcement. I have three things to announce instead. 🙂
Discovery Library for PHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher
A super cool thing that you might not know about with the API An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. is that it’s entirely discoverable. We use a relatively simple process modelled after Atom/RSS feed RSS is an acronym for Real Simple Syndication which is a type of web feed which allows users to access updates to online content in a standardized, computer-readable format. This is the feed. discovery. All you need to do is check a site’s headers for a Link header The header of your site is typically the first thing people will experience. The masthead or header art located across the top of your page is part of the look and feel of your website. It can influence a visitor’s opinion about your content and you/ your organization’s brand. It may also look different on different screen sizes.:
Link: <http://example.com/wp-json/>; rel="https://api.w.org/"
This allows a tonne of possibilities, including renaming the API base, or even delegating API access to someone else. (For example, WordPress.com An online implementation of WordPress code that lets you immediately access a new WordPress environment to publish your content. WordPress.com is a private company owned by Automattic that hosts the largest multisite in the world. This is arguably the best place to start blogging if you have never touched WordPress before. https://wordpress.com/ could use https://api.wordpress.com/{site_id}/ instead of per-site APIs.)
However, this isn’t always the easiest process to use (even if you have an advanced degree in hypothetical topology). To simplify this, we now have a discovery library for PHP 5.3+.
To use it, add wp-api/discovery to your Composer requirements manually or run composer require wp-api/discovery in your project directory. You can then use the WordPress\Discovery\discover() function to discover the API for a given URL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org. (Oh hey, namespaces!)
The library also includes a demo that you can run using PHP’s built-in server, and we’re working on getting a public version of this up on wp-api.org so you don’t even need to install it.
This should simplify the discovery process for everyone, and I’m hoping some wonderful folks in the community will help port this to other languages as well. (Hint hint.)
New OAuth Server
One of the weakest points of developing with the API right now is getting authentication working. For a long time, our OAuth server plugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party has languished and fallen behind as we push forward with the API. No longer is this the case!
Simply update to the latest master. This will also be available on WordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/ very soon.
This new version of the OAuth server has a bunch of changes, including:
- Full admin (and super admin) UI User interface, including application management and the ability to revoke tokens
- Ability to delete applications or regenerate their secrets
- Callback validation process overhaul, now supporting custom protocols
- Overhauled internals
In addition to this, I wanted to address one of the biggest problems with the OAuth process: documentation. The documentation for the OAuth server and process has been terrible in the past. Previously, I’d indicated to people that they should just go read the generic OAuth 1.0a documentation on the web and try with that, but as it turns out, there’s no good documentation on this. (Apologies to those of you who’ve struggled in the past.)
Thankfully, this is now fixed, with a guide included and available on Gitbook. This is an initial version of the guide, and I imagine it’ll grow and improve further in the future.
If there’s anything missing you’d like added or improved, file an issue on the plugin repo. (The guide’s source is also included with the plugin.)
Demo API Client
(pause for breath)
Combining all these pieces, there’s now a demo API client in PHP that you can download and run to try all of this out. The demo client uses the discovery library to find your site, then connects with OAuth to display your user details. Again, you can run this locally using PHP’s built-in server, and we’re working on getting a version set up on wp-api.org too.
Internally, this uses the wonderful OAuth 1 client library by The League of Extraordinary Packages. This repo also acts as a provider for that library, allowing you to use the library in your own code to handle OAuth.
(Both the discovery library and the demo client are open source Open Source denotes software for which the original source code is made freely available and may be redistributed and modified. Open Source **must be** delivered via a licensing model, see GPL. and MIT licensed, allowing you to use them in commercial projects should you so desire.)
Hopefully you find these pieces useful. As always, your feedback on all of this is much appreciated; we’d also love to see discovery libraries and demo clients in other languages, if anyone wants to port them across. Thanks for being great.
#feature-plugins, #json-api, #rest-api
