RESTful APIs - Part 2

Last time I mentioned REST and talked a bit about how nice RESTful APIs are. Now we are going to cover what REST means and what RESTful APIs are.

First, REST is an acronym for representational state transfer and is a style often used for building communications interfaces. Normally it is used with HTTP and so is mostly for web communications.

Two of the basic attributes of most RESTful APIs are also some basic attributes of HTTP. In particular, HTTP request methods and HTTP status codes. It may seem strange that REST is so closely tied to HTTP but the creator of the term REST was involved in the helping with the HTTP specification that allows for REST. If you want to read more about it here is a link to a discussion board post where Fielding discusses REST and HTTP.

HTTP Request Methods

In HTTP there are request methods which are part of the header information and give a general idea of what the request is intended to do. In REST these are used but are often called verbs.

The most commonly used verbs from HTTP are: GET, POST, PUT, and DELETE. There are others that can be used but they are less common.

These verbs were intended to be pretty self explanatory but there are a couple that can be confusing at first, and there is more to how they are used so I will show you how they are generally used and give some examples.

GET

GET is the verb used to get a record or a set of records. One thing about GET is that it has two forms one for getting a list and one for getting a single item.

Lets say we have an API for an orchard. In the orchard API we have fruit so we create an endpoint (path on the URL) for fruit:

/fruit

To get a list of fruit in the orchard we send a GET to the base endpoint and it will return all the fruit available at the orchard.

This is great, except that I actually only want a list of fruit which are ripe. With a GET request we can only pass data in as part of the url as parameters. So if we want to filter our list from the server and the fruit has a property called ripe we could pass in something like:

/fruit?ripe=true

Then if the server is setup to handle that parameter we will get a list of all the ripe fruits in the orchard.

Now we only want a single fruit. Lets say we want Rainier Cherries and the server identifies fruits by their name, normally the id is unique number or string. So with a RESTful API you would send a GET request using the base endpoint followed by the item identifier. So our request for Rainier Cherries would look like:

/fruit/rainier-cherries

This will the return a single record for Rainier Cherries which would let us write an application that keeps checking the orchard to see when they are finally ripe.

POST

POST is not as descriptive as GET. What it does it lets you post a new record. So if we were maintaining the orchard and planted a new tree, lets say a Fuji Apple then we would send POST to the base endpoint with the information for the new fruit in the body of the request instead of as a parameter in the URL string.

Most of the JavaScript libraries or frameworks will let you attach to the body either through a body or data option. Normally body is a JSON string but again many libraries and frameworks will automatically convert your JavaScript object into JSON before sending it.

Our POST request will go to:

/fruit

and the body will look like:

{
    "name": "Fuji Apple",
    "color": "red",
    "season": "Late Fall"
}

Notice I did not include an id? That is because most API's have the server create the id when a new record is posted, though some API's do allow you to include the id.

PUT

PUT is the verb that probably is the least helpful as far as telling the user what it means. PUT lets you put changes to a record. As with POST, PUT uses the body to send the information. We also add the id to the URL the same as we do when getting a single record so we know which record to update. Normally with PUTs you send the whole record with the updates.

I have seen quite a few APIs that only send the field(s) that have changed but this really is for a different verb called PATCH which is like PUT but intended for situations where you only send the changes.
Lets say we need to update the Fuji Apple so the season is a month so that it matches our other fruits so we would send a PUT request to:

/fruit/fuji-apple

and our updated body will look like:

{
    "id": "fuji-apple",
    "name": "Fuji Apple",
    "color": "red",
    "season": "October"
}

Notice that the id is included this time, as I mentioned with a PUT you should be sending the full record.

DELETE

DELETE is another fairly obvious verb. DELETE tells the server to delete a record. To delete a record we need to include its id in the URL the same a as a PUT or a GET for a single record.

So if our Fuji Apple dies then we can send a DELETE request to:

/fruit/fuji-apple

The server will then delete the Fuji's record and everyone will be sad and have to cancel their Fuji eating contests.

Next Time

Next up we will look at RESTful responses and at some point we will talk about tools for designing, creating, documenting, and testing RESTful API's.

comments powered by Disqus