REST and RESTful APIs

I have previously discussed the APIs and why you need them. In this article, we take a deep dive into a fundamental technology we need to develop API.
My intention in writing these articles is to explain relatively complex technologies in an easy-to-understand manner that would benefit my audience.

REST

REpresentational State Transfer, or REST, is an architectural style for providing standards between computer systems on the web, making it easier for systems to communicate. 

Let’s start by introducing two key terms in REST:

• Client: What we call a Client is a software that uses our API.
• Resource: A resource could be any object that we can request information about it from the API. 

In the case of a payment gateway API, a client could be your app that uses the API, and a typical resource could be the credit card token. Your software makes a call to the gateway API to get a credit card token (the resource).

In the REST architecture, the client sends a request to retrieve, add, or modify resources, and servers respond to these requests. 

Web services that conform to the REST architectural style, called RESTful Web services.

A RESTful web service exposes information about itself by providing information about its resources. It also enables/allows the client to interact with its resources and take certain actions on them as well.

There are four basic HTTP verbs (actions) we use in requests to interact with resources in a REST system:

GET: retrieve a specific resource or a collection of resources

POST:  create a new resource

PUT: update a specific resource 

DELETE: remove a specific resource

Stateless System

For an API to be RESTful, you have to follow a set of constraints when you create it. Systems that follow the REST paradigm are stateless.

In a stateless system, both the server and the client can understand any message received, even without seeing previous messages (or state).

Consider the example below:

Stateful: Checking your Credit Card Transactions

Imagine you need to check your credit card transactions. You have to log in to your gateway account first. Before you request any information, the server must make sure that you have logged in, and it authenticates your credentials to make sure that you are an authorized user. 

Your state is essential in every step before the gateway server answers to your requests.

Stateless: Getting credit card transactions by using an API

In contrast to the above example, if you have an application that makes API calls to a RESTful web service, in each call, you send your request along with your credentials, and the API gets responses from you.

In this case, when you (the client) make an HTTP request, it includes all information necessary for the server to fulfill that request. The server never relies on information from your previous requests. You (the client) send the critical information which each request that you make.

In Short

A stateless system does not require the server to retain session information or status about each communications partner for the duration of multiple requests.

In a stateful system, the client connects to the server, conducts a series of operations via that connection, and then disconnects. Then the server can associate all of the requests together and knows that thy all came from the same user.

Making a request

In REST, the client sends a request to the server to retrieve or modify data on the server. 

For example, when a developer calls Authorize.Net API to fetch a specific payment record (the resource), the API returns the state of that record, including its amount, card type, date, the name on the card, and other details. 

For most APIs, the representation of the state is in a JSON format. The other standard format is XML.

A request generally consists of:

• One of the HTTP verbs, to identify what kind of operation you intend to perform
• a header, which allows the client to pass along information about the request
• a path to a resource (we call this an endpoint)
• A message body containing data

Concise form:

• The identifier of the resource you are requesting. The identifier is a URL for the resource, aka endpoint. 
• An HTTP verb (GET, POST, PUT, and DELETE) indicates the type of operation on your requested resource.

HTTPS verbs perform Create, Read, Update, and Delete (CRUD) operations on a resource.

The HTTP verbs comprise a significant portion of our “uniform interface” constraint and provide us the action counterpart to the noun-based resource. 

POST -> Create

GET -> Read

PUT -> Update

DELETE -> Delete

There are some other verbs, too, but used less frequently.

POST

The POST verb performs “create operation” of new resources. When creating a new resource, POST to the parent, and the service takes care of associating the new resource with the parent, assigning an ID (new resource URI).

Examples:

POST-http://www.example.com/customers
POST-http://www.example.com/customers/12345/orders

GET

The GET verb performs a “read operation” to retrieve a resource.

Examples:

GET - http://www.example.com/customers/12345
GET - http://www.example.com/customers/12345/orders
GET - http://www.example.com/buckets/sample

PUT

The PUT verb performs an “update operation” on the resource.

Examples:

PUT - http://www.example.com/customers/12345
PUT - http://www.example.com/customers/12345/orders/98765

DELETE

The DELETE verb performs a “delete operation” of a resource identified by a URI.

Examples:

DELETE - http://www.example.com/customers/12345
DELETE - http://www.example.com/customers/12345/orders

Endpoints

Each request must contain a path to a resource that is the target of an operation. In RESTful APIs, we call these paths Endpoints.

Conventionally, the first part of the endpoint should be the plural form of the resource. 

https://example.com/customers/912/orders/23

We can see that we are accessing the order with id 23 for the customer with id 912.

Endpoints must include the necessary information to locate a resource. If referring to a list or collection of resources, there is no need for an ID. 

https://example.com/customers/

When you are trying to access a specific resource, you need to attach an id to the endpoint. 

http://www.example.com/customers/10000

Responses

You send a request pointed at an endpoint, and the API receives a response to our request from the server.

The server sends a data payload to the client (via API). The server also includes a content-type in the header of the response. 

The content-type tells the client about the format of the data in the response body.

HTTP/1.1 200 (OK) 
Content-Type: text/html

Request header uses accept to tell the server about the format of the coming data:

GET /articles/23 HTTP/1.1 
Accept: text/html, application/xhtml

Response Codes

Responses from the server contain status codes. A status code informs the client about the success or failure of an operation. You do not need to know every status code, but knowing the usual codes and their meaning is useful:

200 (OK) Successful HTTP requests
201 (CREATED) an item successfully created
204 (NO CONTENT) Nothing in the response body.
400 (BAD REQUEST) The request cannot be processed because of bad request syntax, excessive size, or another client error.
403 (FORBIDDEN) The client does not have permission to access this resource.
404 (NOT FOUND) The resource could not be found at this time.
500 (INTERNAL SERVER ERROR) The generic response for an unexpected failure

For each HTTP verb, there are status codes a server should return upon success:

GET — return 200 (OK)
POST — return 201 (CREATED)
PUT — return 200 (OK)
DELETE — return 204 (NO CONTENT)

Examples

POST

Request:

GET http://example.com/customers
Accept: application/json

Response Header:

Status Code: 200 (OK)
Content-type: application/json

Response data payload:

POST http://example.com/customers
Body:
{
  "customer": {
    "name" = "John Doe"
    "email" = "john.doe@example.com"
  }
}

The server then generates an id for that object and returns it back to the client, with a header like:

201 (CREATED)
Content-type: application/json

GET

Request

GET http://example.com/customers/100
Accept: application/json

Response header:

Status Code: 200 (OK)
Content-type: application/json

The data for the customer resource with id 100 follows the header in application/json format.

PUT

Request

http://example.com/customers/100
Body:
{
  "customer": {
    "name" = "Jane Doe"
    "email" = "jane.doe@example.com"
  }
}

A possible response header would have Status Code: 200 (OK). The client knows that the item with id 100 updated successfully.

DELETE

We can also DELETE that customer by specifying its id:

DELETE http://example.com/customers/100

Final word

As you saw in this article, REST architecture is compelling, and developers have embraced REST to build RESTful APIs, using them to add functionality to their applications, while keeping their application quick, small and agile. REST APIs are considered the “backbone of the Internet.”