What is a REST API - everything you need to know
Tags: rest, api, cs, computerscience
Published: 2019-11-15 13:39:58

---
title: What is a REST API - everything you need to know
published: true
date: 2019-11-13 00:00:00 UTC
tags: ['REST', 'API', 'CS', 'computerscience']
canonical_url: https://www.mariokandut.com/what-is-a-rest-api-everything-you-need-to-know
---

_This article was originally published on [mariokandut.com](https://www.mariokandut.com/what-is-a-rest-api-everything-you-need-to-know)._

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](https://en.wikipedia.org/wiki/Roy_Fielding) created this architectural style in 2000 in his [disertation](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm).

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.**

<u>For example</u>: When you make a request to the [github API](https://developer.github.com/v3/) 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](https://www.twitter.com/mariokandut)**.

Here are some articles to help you learn RESTful APIs: [MDN HTTP methods](https://developer.mozilla.org/de/docs/Web/HTTP/Methods), [MDN HTTP Status Codes](https://developer.mozilla.org/de/docs/Web/HTTP/Status), [wikipedia](https://en.wikipedia.org/wiki/Representational_state_transfer), [RESTfulapi.net](https://restfulapi.net/), [Shif Ben Avraham](https://medium.com/extend/what-is-rest-a-simple-explanation-for-beginners-part-1-introduction-b4a072f8740f), [Goran Aviani](https://www.freecodecamp.org/news/http-and-everything-you-need-to-know-about-it/), [Preethi Kasireddy](https://www.freecodecamp.org/news/how-the-web-works-part-iii-http-rest-e61bc50fa0a/).