in Tutorials

WebServices by example 1 of 3

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.

The theory

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)
  • Content-type
HTTP Methods

To implement a RESTful api, the following HTTP methods must be implemented for each resource.

HTTP Methods
HTTP MethodDescription
POSTCreates a resource
GETFetches a resource
PUTUpdates a resource
DELETEDeletes 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

HTTP Status codes
CodeMeaning
200OK
201Created
304Not Modified
400Bad Request
401Unauthorized
403Forbidden
404Not Found
500Internal 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.

Content Type

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.


 So far

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:

Alright! now with the theory out of the way, let us get busy with an example.

WebServices by example 2 of 3 is now available.