Before we go any further ahead, let us discuss some key considerations that are useful to bear in mind when working with RESTful applications and services.
Note
Since REST is an architectural style and not a standard, the following are considerations and not totally mandatory rules.
When working with WordPress, the following key considerations are something you should bear in mind. The question is, why so?
It is because many times you will be using REST API to communicate with services that may not be running on WordPress (for example, a third-party social network that your plugin might interact with). As such, if you follow the following norms when working with REST API in WordPress, you won't have to face issues with uniformity.
The architecture of RESTful services is pretty straightforward and we can briefly summarize its main components as follows:
Resources are the key components of RESTful services. They are identified by logical URLs and are universally accessible by other parts of the system.
Resources should contain links to other information, much like web pages. Thus, resources should be interconnected.
Resources can be cached.
Note
Since HTTP is what RESTful services used, the HTTP cache-control headers are sufficient for this task.
RESTful systems follow the client-server model.
Standard HTTP proxy servers can be used in RESTful architecture.
REST services can interact with non-REST services, and vice versa.
REST is more of a style and less of a standard, so there are not many design principles to consider. In general, this is what you should follow:
GET requests should not cause a change in state or alter data. If you wish to modify the state or data, use POST requests.
Pagination is always a good practice; if your GET query reads entries, let it read the first N number of entries (for example, 20) and then use links to read more entries.
Physical URLs are considered a bad practice, and logical URLs should be preferred.
If the REST response is in XML, consider using a schema.
Also, for documenting a REST service, you can use Web Services Description Language (WSDL) or Web Applications Description Language (WADL). Both are feature-rich, but WSDL offers more flexibility as it does not bind itself to Simple Mail Transfer Protocol (SMTP) servers, whereas WADL is easier to read and interpret. And if either of them does not appeal to you, a simple HTML document too can suffice.