REST (REpresentational State Transfer) defines commonly used API semantics that utilize HTTP to share and manage resources. REST focuses on performing HTTP methods (verb) on resources (noun) which return well-defined HTTP responses.
For this post, we will go through REST examples using a coffee shop and see what REST calls may look like for the various transactions.
It All Began With Coffee
This example begins with Bob (a not-so-morning person) entering the coffee shop for his day’s first coffee. He orders his usual black coffee.
The HTTP request may look something like this:
Method: POST
URL: http://www.example.com/shop/coffee
Body:
{
status: NEW,
roast: DARK,
numSugars: 0,
hasCream: false,
flavors: []
}
Since this is a new order a POST was used to create it. It was specified on the coffee resource to create a new coffee order. The request contained a body specifying the details of the order.
As a result of the new order, the response contains a Location header field containing the new order: http://www.example.com/shop/coffee/75
In this example, 75 represents the ID of the order. This value was used to keep the example simple. An ID can be represented as a randomly generated UUID (i.e. d918647c-9c4e-438f-af69-b927f02eec72). One of the benefits of UUIDs is they are harder for attackers to predict or guess.
A Spark of Change
Alice, one of Bob’s friends, walks in and convinces Bob to try the new peppermint mocha signature coffee. He quickly requests to change his order.
His new request may look something like this:
Method: PUT
URL: http://www.example.com/shop/coffee/75
Body:
{
status: NEW,
roast: LIGHT,
numSugars: 1,
hasCream: true,
flavors: [peppermint, mocha]
}
A PUT request essentially replaces the existing resource. All values are defined.
PUT requests are idempotent, meaning that multiple requests have the same final result (an updated resource in this case).
POST requests are not idempotent. Three POST requests results in three created items.
Bob can request a partial update if the order by using the PATCH method:
Method: PATCH
URL: http://www.example.com/shop/coffee/75
Body:
{
roast: DARK
}
This request only updates the specifies fields.
Canceling an Order
Bob accidentally created a duplicate order. He can cancel it using the following request:
Method: DELETE
URL: http://www.example.com/shop/coffee/76
The Sweet Smell of Coffee
As Bob waits for his order, he can check its status by using a GET request:
Method: GET
URL: http://www.example.com/shop/coffee/75
When you enter a URL in the browser navigation bar, the browser issues a GET request for that resource.
GET requests should not modify resources. This is important because web crawlers use GET requests to find resources, causing unintended modifications if side effects are allowed.
Key Takeaways
In this overview we covered an example of using a RESTful API.
We saw coffee orders represented as a resource within the URL.
We performed serveral actions (POST, PUT, PATCH, DELETE, GET) on an order to interact with it.