REST is one common approach related to building web applications. It is one important term that all web application developers should understand. This is the main goal of this REST API tutorial. Furthermore, a good understanding of what is REST can be beneficial for other stakeholders as well.

Table of Contents

Introduction to the REST API

This article is a REST API tutorial, which will guide you through the main concepts of REST. Also, this tutorial includes vocabulary and examples related to REST.

Firstly, we will go through the basic concepts. Secondly, we will learn about the vocabulary used in the API world. Finally, we will talk some more about RESTful API and provide some examples for further learning.

Finally, there is another article that I wrote which discusses what are the best practices for REST API design.

What is an API?

API stands for Application and Programming Interface. Furthermore, API allows one piece of software to talk with some other piece of software.

There are lots of different kinds of APIs, for example, Facebook API, Twitter API, etc. Nevertheless when people talk about these APIs, most of the time they are referring to REST API.

REST API tutorial – What is REST?

REST stands for Representation State Transfer, but what does this actually mean?

For example, let us talk about Twitter. Before Twitter API existed this service provided a way to make tweets, like, share them, view trends, etc. But, all these things had to be done with the Twitter website.

When Twitter created API, they enabled the use of these functionalities by external sources (external applications). Because of this, other developers can create applications (desktop or mobile) that can send tweets and do all these things that Twitter can.

For a more graphical explanation, let’s look at a REST API diagram.

API example diagram
REST API example diagram

Consumer is a person. This person has access to a simple mobile application. This application has two buttons “give me data” and “upload data”.

When user clicks on “give me data” button, mobile application executes an request toward service provider.

Firstly, the API endpoints handler turns these requests into a standard function. These functions do some logic inside a service provider. This logic checks if the user has the right to ask for that data. Furthermore, it checks what amount of data users can have.

Secondly, data is prepared for user. As a result, REST API provider delivers data in XML or JSON format to mobile application.

Finally, mobile application takes this data and makes some graphical representation for user.

Some important details:

  • Client will most likely be authenticated in some way, before being able to ask for data or send data.
  • Furthermore, a client can execute different REST API endpoints, to get or send different data.
  • Finally, Client can execute REST API calls multiple times.
  • This is a common use case of REST API. Most of mobile apps today use one or multiple APIs to provide some kind functionality.

Important vocabulary for REST API

Are you familiar with REST API vocabulary? Read through the list below and see if you understand the most important terminology.

  • API – Application and Programming Interface
  • REST – Representation State Transfer
  • Client – Entity that is using API, by executing HTTP(s) calls against API “endpoints”
  • Server – Entity that serves API, by providing a response to HTTP(s) calls received on “endpoints”
  • HTTP – HyperText Transfer Protocol is a web protocol that defines how messages are formatted and transmitted. Furthermore, HTTP describes actions Web servers and browsers should take in response to various requests.
  • Endpoints – links that represent the functionalities of API that clients can use.
  • HTTP verbs – different actions that can be executed against endpoints. For example READ, POST, UPDATE or DELETE.
  • Parameters -Parameters of the request. These parameters can be header or body parameters.
  • Permissions – set of permissions that the client has related to some API. In most of the cases, these are related to tokens.
  • Limitations -Set of limitations that the client has related to some API.
  • Token -Authorization mechanism, a more secure version of a username/password combination.
  • Grant Token Type -Different ways of getting token from some API and using it. This is a very complex topic.
  • OAuth -Open Authorization protocol
  • JSON -Lightweight data interchange format
  • cURL – Library for executing various protocols from the command line. It can be used to execute HTTP requests from the command line.
  • Postman -Free software for executing API requests (from the graphical dashboard). A very useful and must-have tool for API developers.

Authentication of REST requests

Well, most of the time REST API acts like a website, where some Client would contact Server with HTTP(s) requests.

As a result, the server will return the current state of data, related to that API call.

Meaning, if the Client want’s to get new data (a refreshed data) then he will execute a new REST API call towards the server.

Authentication of REST request is done via tokens.

One of the most common use cases is token-based authentication and authorization with OAuth. This link will lead you to one article where I explained OAuth authentication and authorization.

REST vs RESTful?

Once again, REST is a style of software architecture, nothing more. Moreover, this is a set of rules which should be implemented to make a software solution REST.

Meaning that REST, or REpresentational State Transfer, is a design style for building APIs (Application Programming Interfaces). It is not a standard or a protocol, but it is an architectural pattern that guides the design of web APIs. The main principles of REST include separation of concerns, statelessness, caching, and a uniform interface.

RESTful refers to an API that follows the REST architectural pattern. So, if an API is RESTful, it means that it follows the principles of REST. However, it is important to note that not all REST APIs are RESTful, as they may not follow all of the principles of REST.

In his dissertation, Roy Fielding described REST is an “architectural style” that basically exploits the existing technology and protocols of the Web.

Term “RESTful” is usually used to describe web services which implement REST architecture.