I have built many WebServices APIs over the years. I dealt with multiple server CMS platforms (WordPress, Joomla), in-house servers, PHP, ASP many of which needed some form of RESTful api to communicate with mobile applications.
Here’s the first of a three part tutorial that develops a RESTful web service by example.
We must all start from a common ground, so I’ll put forward a few definitions in order for all of us to be on the same page.
What is REST and RESTful API?
Representational state transfer (REST) is a software architectural style consisting of a coordinated set of architectural constraints applied to components, connectors, and data elements, within a distributed hypermedia system. REST ignores the details of component implementation and protocol syntax in order to focus on the roles of components, the constraints upon their interaction with other components, and their interpretation of significant data elements — Wikipedia
Put simply, its a standardized way for communicating data, objects and connections between a client and server applications using the HTTP protocol.
It’s recommended to use RESTful api for web services, as it makes the API more lean and descriptive.
All data in a RESTful api is divided into two types of models: collections and resources.
A Resource is an object that holds the data model to be manipulated.
A Collection is a grouping of resources with a common bond
Other important concepts about RESTful APIs and for which we must define for our web service are
- HTTP methods
- HTTP Status Codes
- URI (URLs)
To implement a RESTful api, the following HTTP methods must be implemented for each resource.
|POST||Creates a resource|
|GET||Fetches a resource|
|PUT||Updates a resource|
|DELETE||Deletes a resource|
HTTP Status Code
IF you’re familiar with HTTP protocols, a status code is returned by the server for each HTTP request. Your application API doesn’t have to implement all of them to be complete, but the following should be enough for 99% of all applications, for a complete list, please see Wikipedia
|500||Internal Server Error|
URI (URL endpoint)
For RESTful api, the URL endpoint is tied to a Resource. That’s why it should be well formed and should be human readable. Each URL endpoint must be unique to each Resource.
For example, a resource called Tasks will have a URI that looks like:
GET http://somesite.com/tasks/22 – Will return the content of task with id=22 POST http://somesite.com/tasks – Will create a new task
side note: Always make a resource endpoint name in the plural form (task becomes tasks, goose becomes geese) this way it will be easier for keeping readability of the api easier.
The HTTP header “Content-Type” specifies the format in which data is communicated between both the server and client. Depending on your needs, there are a lot of content-types that you can chose from (look here).
But from experience, the most used and by far the easiest content-type is application/json. The JSON content-type is well supported in all major modern languages.
We went through a lot of lingo. If you were new to this, you need time to absorb what was discussed. I also recommend further reading at the following site:
- Thoughts on RESTful API Design by Geert Jansen
Alright! now with the theory out of the way, let us get busy with an example.