Components of REST API

What Is a REST API?

REST (Representational State Transfer) is a software architectural style that defines certain constraints for accessing a resource on a server. REST is a highly popular web API type because it offers flexible, fast, and simple communication between RESTful web applications. Compared to other API formats, REST is by far the most used, as over 80% of public web APIs are RESTful. They mostly communicate using the HTTP(HyperText Transfer Protocol) using JSON, XLT, HTML, XML, or simple text message formats. Out of these data formats, JSON is the most common as it is widely accepted by the industry as a whole.

Components of a REST API

A typical REST API consists of the following parts:

URL

Request Method

Request Headers

Request body

Response Code

Response Headers

Response body

URL

Under REST principles, a URL identifies a resource. An URL is made up of scheme, host, port, path and query parameters as follows:

<scheme>://<hostname>:<port>/<path>?<query-parameters>

The 'scheme' is the transfer protocols used by the API. In general it may be http, https, ftp, file etc. But in RESTful API world it is usually http or https.

The 'hostname' is the server or IP address (IPv4) of the host that hosts the API.

The 'port' is a number and is the network port on which the server is listening for incoming connections. It is an optional field in the URL and required only if it is different from the scheme's default port (80 for HTTP and 443 for HTTPS).

The 'path' is the location of a resource(static or dynamic) on the server. Each path should uniquely identify a resource. The path can further be broken down into base path and the sub paths. Base path is the URL prefix for all resources on the server, relative to the host root. It must start with a leading slash /. If base path is not specified then all endpoint paths start at the host root. For example, consider the following APIs:

https://www.bookstore.com/books/harry-potter
https://www.bookstore.com/books/lord-of-the-rings

Here the "/books" is the base path. In REST, the path can take parameters also. Path parameters are part of the endpoint itself and are not optional. For example, in the following endpoint, {user} and {bicycleId} are required path parameters:

    /service/myresource/user/{user}/bicycles/{bicycleId}

Path parameters are usually set off with curly braces, but some API doc styles precede the value with a colon or use a different syntax. When you document path parameters, indicate the default values, the allowed values, and other details.

The 'query-parameters' is a key-value pair required by the API to do the necessary tasks and produce an output. We can think them as options that can be passed in the URL to influence the response. Query parameters appear after a question mark (?) in the endpoint. The question mark followed by the parameters and their values is referred to as the "query string". In the query string, each parameter is listed one right after the other with an ampersand (&) separating them. The order of the query string parameters does not matter. For example, an API might look like

https://www.company.com/employees?firstname=john 

which returns all employees with first name 'John'.

Another example is

https://www.bookstore.com/books/harry-potter startPage=100&endPage=200 

which can give all the pages starting from 100 to 200.

Each collection and resource in the API has its own URL. URLs should are not constructed by a client calling the API. Instead, the client should simply follow the server's API documentation and construct the API.

Request method

The request method of an API specifies the type of operation requested by the client from the server. The same API can support different methods. The following are some of the most common request methods used:

    GET - Used to read a resource and its details
    POST - Used for creating a resource on the server
    PUT - Used to update an dexisting resource on the server
    DELETE - Used to delete a resource on the server

There are other methods like HEAD, PATCH etc that are available but less commonly used.

Request Headers

The Request headers are name value pairs that are added to the HTTP request that carry a variety of information that the server needs to successfuly process the request. Following are some of the exampe headers:

Authorization - header that carries the authorization information if the resource being accessed is restricted.

Content-Type - tells the server about the format of the request body(Json, XML, text, etc)

User-Agent - tells the server about the type of the client(like firefox, chrome, safari, edge etc..)

The server can also define custom headers specific for an API. In that case the API provider should document them in the parameters documentation within each API endpoint.

Request body

When you need to send data from a client (let's say, a browser) to your API, you send it as a request body.A request body is data sent by the client to your API. A response body is the data your API sends to the client.Your API almost always has to send a response body. But clients don't necessarily need to send request bodies all the time. The request body may be JSON or XML, depending on the content-type header value from the request.

Single entry example-request-body in JSON format.
{
 "name": "user1",
 "id": 1234,
 "roles": [
  {
   "name": "admin"
  },
  {
   "name": "itil"
  }
 ]
}

Response header A response header is a HTTP header that is sent in an HTTP response and may provide information about the resource being returned. It cam also contain other information required by the client but not reated to the actual response content. For example, response headers like Age, Location or Server are used to give a more detailed context of the response. Not all headers appearing in a response are categorized as response headers by the specification. For example, the Content-Type header is a representation header indicating the original type of data in the body of the response message (prior to the encoding in the Content-Encoding representation header being applied). However, "conversationally" all headers are usually referred to as response headers in a response message. The following shows a few response and representation headers after a GET request. 200 OK Access-Control-Allow-Origin: * Connection: Keep-Alive Content-Encoding: gzip Content-Type: text/html; charset=utf-8 Date: Mon, 18 Jul 2016 16:06:00 GMT Etag: "c561c68d0ba92bbeb8b0f612a9199f722e3a621a" Keep-Alive: timeout=5, max=997 Last-Modified: Mon, 18 Jul 2016 02:36:04 GMT Server: Apache Set-Cookie: mykey=myvalue; expires=Mon, 17-Jul-2017 16:06:00 GMT; Max-Age=31449600; Path=/; secure Transfer-Encoding: chunked Vary: Cookie, Accept-Encoding X-Backend-Server: developer2.webapp.scl3.mozilla.com X-Cache-Info: not cacheable; meta data too large X-kuma-revision: 1085259 x-frame-options: DENY Response codes The response codes are sent by the server indicating to the client about the outcome of the request processing. 200 Series - Represents a successful processing of the request. 200 – OK 201 – Created 202 – Accepted 203 – Non-Authoritative Information 204 – No Content 400 Series - Represents client-side error. 400 – Bad Request 401 – Unauthorised 402 – Payment Required 403 – Forbidden 404 – Not Found 408 – Request Timeout 422 – Unprocessable Entity 500 Series - Represents server-side error. 500 – Internal Server Error 501 – Not Implemented 502 – Bad Gateway 503 – Service Unavailable Response Body The response body can contain information about the output and additional output ports. If the output type was file, the response body contains a path to the output. If the output type was buffer, the response body contains the buffer contents. The response body can also contain a success or failure code and message.

Hope you learnt something about the components of REST API. Happy Learning!