What is a REST API - everything you need to know

This article was originally published on mariokandut.com.

REST stands for RE presentational S tate T ransfer. It's a software architectural style that defines a set of constraints to be used for creating Web services. Roy Fielding created this architectural style in 2000 in his disertation.

So REST is a architectural style or a design pattern for APIs. It relies on a stateless, client-server, cacheable communications protocol, basically HTTP. The World Wide Web, which is based on HTTP, can be viewed as a REST-based architecture, if you want to go this far.

When a REST API is called, the server will send data (a representation of the state) of the requested resource to the client.

For example: When you make a request to the github API to fetch a specific user (= requested resource). The API will return the state of the user and all the public available information. (In general, a REST api is not limited to public data only.)

Let's try it out:

// Make a request via fetch() or just type this URL in your browser
// https://api.github.com/users/{YOUR GITHUB USERNAME}

You will get all the public available information for your profile back. Below you can see my public data.

  {
    "login": "iepur1lla",
    "id": 17470854,
    "node_id": "MDQ6VXNlcjE3NDcwODU0",
    "avatar_url": "https://avatars3.githubusercontent.com/u/17470854?v=4",
    "gravatar_id": "",
    "url": "https://api.github.com/users/iepur1lla",
    "html_url": "https://github.com/iepur1lla",
    "followers_url": "https://api.github.com/users/iepur1lla/followers",
    "following_url": "https://api.github.com/users/iepur1lla/following{/other_user}",
    "gists_url": "https://api.github.com/users/iepur1lla/gists{/gist_id}",
    "starred_url": "https://api.github.com/users/iepur1lla/starred{/owner}{/repo}",
    "subscriptions_url": "https://api.github.com/users/iepur1lla/subscriptions",
    "organizations_url": "https://api.github.com/users/iepur1lla/orgs",
    "repos_url": "https://api.github.com/users/iepur1lla/repos",
    "events_url": "https://api.github.com/users/iepur1lla/events{/privacy}",
    "received_events_url": "https://api.github.com/users/iepur1lla/received_events",
    "type": "User",
    "site_admin": false,
    "name": "Mario Kandut",
    "company": null,
    "blog": "https://www.mariokandut.com",
    "location": "Vienna, Austria",
    "email": null,
    "bio": "Software Developer with marketing background",
    "public_repos": 47,
    "public_gists": 1,
    "followers": 14,
    "following": 70,
    "created_at": "2016-02-25T09:26:10Z",
    "updated_at": "2019-11-04T16:13:02Z"
  }

A web application, which fulfills the constraints of REST is called RESTful application. It exposes information about requested resources (in the github example above information about the user). But REST also enables you to take actions on the ressources.

RESTful applications use HTTP requests to create data, update data, read data and delete data. Hence, REST uses HTTP for all four CRUD (Create/Read/Update/Delete) operations.

If you follow the REST constraints, it will make your API easier to use and easier to unterstand for new project members or it will even help a future You. REST is also lightweight and Platform-independent (you don't care what OS the server or the client runs on) and Language-independent (C# can talk to Javascript).

So to understand REST you need to understand the basics of HTTP. ( YES , I am going to write a detailed blog post about it.)

As you might know HTTP stands for Hypertext Transfer Protocol. It's a communication protocol you are currently using to read this blog post or anything else on the internet. HTTP is on it's basic level a message-based model. Every interaction involves a request and a response.

Every HTTP request must have an URL, an address where the requested resource is located. Additionally, the request has a method, similiar to the CRUD model. The method indicates what action should be performed with the given resource.

HTTP methods

These HTTP methods are also referred to as HTTP verbs. The most commonly used are:

• The GET method requests a representation of the specified resource. Requests using GET should only retrieve data.
• The POST method is used to submit an entity to the specified resource, often causing a change in state or side effects on the server. Requests using POST should be used to send data and create a resource.
• The PUT method replaces all current representations of the target resource with the request payload. Requests using PUT are used to update a resource.
• The DELETE method deletes the specified resource.

Not so commonly used:

• The HEAD method asks for a response identical to that of a GET request, but without the response body.
• The CONNECT method establishes a tunnel to the server identified by the target resource.
• The OPTIONS method is used to describe the communication options for the target resource.
• The TRACE method performs a message loop-back test along the path to the target resource.
• The PATCH method is used to apply partial modifications to a resource.

HTTP status codes

When you send a HTTP request, you also get a response. There are several response codes, five four main groups:

• 1xx: Information responses
• 2xx: Successful responses
• 3xx: Redirection messages
• 4xx: Client error responses
• 5xx: Server error responses

I'd recommend to memorize these codes and there meaning, it will help a lot when you are debugging.

What makes an API a Restful API

REST defines 6 architectural constraints , which make any web service a RESTful API.

• Uniform interface
• Client-Server
• Stateless
• Cacheable
• Layered system
• Code-on-demand (optional)

Uniform interface

• The request to the server has to include a unique resource identifier
• The response of the server includes enough information so the client can modify the resource.
• Any single resource should not be too large and contain each and everything in its representation. - Whenever relevant, a resource should contain links pointing to relative URIs to fetch related information.
• Also, the resource representations across system should follow certain guidelines such as naming conventions, link formats or data format (xml or/and json).

Client-Server

Servers and clients may also be replaced and developed independently, as long as the interface between them is not altered.

This means that client application and server application MUST be able to evolve separately without any dependency on each other. A client should only know the resources URL and that’s it.

Stateless

No client context shall be stored on the server between requests. The client is responsible for managing the state of the application.

Stateless means here that the server does not remember anything about the client who uses the API. If the client application needs to be a stateful application for the end user (authentication, authorization), then each request should contain all the information necessary including authentication and authorization details.

Cacheable

Well-managed caching partially or completely eliminates some client-server interactions, further improving scalability and performance.

In RESTful architecture caching should be applied to resources, when applicable and then these resources MUST declare themselves cacheable. Caching can be implemented on the server or client side.

Layered system

REST allows you to use a layered system architecture. Between the client who sends the requests and the server who sends the response, there could be a number of servers in between. This means you can deploy the API on server A, store the data on server B and authenticate requests on server C. There can also be a security layer, a caching layer, a load-balancing layer or other layers/functionality added.

Code on demand (optional)

This constraint is optional. In most cases you will be sending the static representations of resources in form of XML or JSON, but you are permitted to return executable code to support a part of your application.

In a nutshell

REST is an architecture style for APIs, which defines how data is requested and received. There is a set of constraints to follow to have a truly RESTful API. To understand REST you need to have an understanding of HTTP methods and HTTP status codes.

I hope I could bring some light in the dark corners of REST and as always, if you have any questions , use the comment function or send me a message on twitter @mariokandut.

Here are some articles to help you learn RESTful APIs: MDN HTTP methods, MDN HTTP Status Codes, wikipedia, RESTfulapi.net, Shif Ben Avraham, Goran Aviani, Preethi Kasireddy.

Comments

[vinuverma]

Excellent!