Getting started with REST implementation

We are now familiar with REST API and JSON. Plus, we also know that REST API is indeed useful in many different ways. Let us now try to put it into practice.

Passing commands in SOAP versus REST

Say, we need to query a given database for user details of a user with ID 1191. Using web services and Simple Object Access Protocol (SOAP), we will be doing something such as the following:

<?xml version="1.1"?> 
<soap:Envelope 
xmlns:soap="http://www.w3.org/2001/12/soap-envelope" 
soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding"> 
<soap:body pb="http://www.example.com/database"> 
<pb:GetUserDetails> 
<pb:UserID>1191</pb:UserID> 
</pb:GetUserDetails> 
</soap:Body> 
</soap:Envelope> 

The preceding code will give us an embedded XML file inside a SOAP response envelope.

And how will we do this using REST? The following way: http://www.example.com/database/UserDetails/1191.

Yes, that is all. It is a simple URL with GET request, and the response will give us the raw data, that is, the details of the user with ID 1191. While in SOAP, we needed multiple libraries to parse the response, in REST, we just need to pass the simple URL. We can even test the API directly right within the browser as a simple request.

Of course, the preceding example is a simplified case, and if need be, REST libraries do exist. However, as it becomes clear, REST is way simpler than web services and other counterparts.

Tip

Downloading the example code You can download the example code files for this book from your account at http://www.packtpub.com. If you purchased this book elsewhere, you can visit http://www.packtpub.com/support and register to have the files e-mailed directly to you. You can download the code files by following these steps:

1. Log in or register to our website using your e-mail address and password.
2. Hover the mouse pointer on the SUPPORT tab at the top.
3. Click on Code Downloads & Errata.
4. Enter the name of the book in the Search box.
5. Select the book for which you're looking to download the code files.
6. Choose from the drop-down menu where you purchased this book from.
7. Click on Code Download.

You can also download the code files by clicking on the Code Files button on the book's webpage at the Packt Publishing website. This page can be accessed by entering the book's name in the Search box. Please note that you need to be logged in to your Packt account.

Once the file is downloaded, please make sure that you unzip or extract the folder using the latest version of:

• WinRAR / 7-Zip for Windows
• Zipeg / iZip / UnRarX for Mac
• 7-Zip / PeaZip for Linux

The code bundle for the book is also hosted on GitHub at https://github.com/PacktPublishing/Learning_WordPress_REST_API. We also have other code bundles from our rich catalog of books and videos available at https://github.com/PacktPublishing/. Check them out!

Handling data in REST

For complex operations, the methodology remains similar. Let us refine the preceding query and look for the user with first name Sample and last name User as follows: http://www.example.com/database/UserDetails?firstName=Sample&lastName=User.

As we can see, for longer parameters, we are including the parameters within the body of the HTTP POST request. At this point, it is useful to discuss REST requests in themselves.

For simpler queries of a read-only nature, GET is the de facto standard. However, for read-only queries that are complex in nature, POST requests can be used. Of course, POST requests are also used for queries that can change the state of the data and deal with creation, updating, and deletion of data.

If you are wondering how to distinguish a simple query from a complex one, consider this: when reading a blog, you send a GET request as a simple query to open the page, but if you decide to post a comment on the blog post or share it via any of the social networks, you send a POST request with additional and more complex details.

And in terms of server responses, RESTful services can handle XML, CSV, and JSON. Each of these formats has its own advantages: XML, for example, is pretty easy to expand, CSV is compact and lightweight, whereas JSON is easy to parse. As you might have guessed by now, for WordPress REST API, JSON is the way to go, all thanks to JavaScript.

Note

Unless the response needs to be read by humans, HTML is not the de facto choice for REST server responses. Of course, since almost everything on the World Wide Web needs to be read by humans, HTML is being used as a server response for RESTful services.