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 trough the basic concepts. Secondly, we will learn about vocabulary used in API world. Finally, we will talk some more about RESTful API and provide some examples for further learning.
What is an API?
API stands for Application and Programming Interface. Furthermore, API allows one peace of software to talk with some other peace of software.
There are lots of different kinds of APIs, for example Facebook API, Twitter API, etc. Nevertheless when people talk about these API, most of the times they are referring to REST API.
REST API tutorial – What is REST?
REST stands for Representation State Transfer, but what does this actually means?
For example, lets talk about Twitter. Before Twitter API existed this service provided a way to make tweets, like, share them, view trends etc. But, all this things had to be done with Twitter web site.
When Twitter created API, they enabled use of these functionalities by external sources (external applications).
Because of this, other developers can create applications (desktop or mobile) which can send tweets and do all these things that Twitter can.
For a more graphical explanation, let’s look at a REST API 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, API endpoints handler turns these requests into a standard functions. These functions do some logic inside a service provider. This logic checks if user has right to ask for that data. Furthermore it checks what amount of data user 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
- API – Application and Programming Interface
- REST – Representation State Transfer
- Client – Entity which is using API, by executing HTTP(s) calls against API “endpoints”
- Server – Entity which serves API, by providing a responses to HTTP(s) calls received on “endpoints”
- HTTP – HyperText Transfer Protocol is web protocol which defines how messages are formatted and transmitted. Furthermore, HTTP describes actions Web servers and browsers should take in response to various requests.
- Endpoints – links which represent a 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 which client has related to some API. In most of the cases, these are related to token.
- Limitations -Set of limitations which client has related to some API.
- Token –Authorization mechanism, more secure version of 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 command line. It can be used to execute HTTP requests from command line.
- Postman -Free software for executing API requests (from graphical dashboard). Very useful and must have tool for API developers.
Well, most of the time REST API acts like a web site, where some Client would contact Server with HTTP(s) request. As a result, the server will return current state of data, related to that API call. Meaning, if Client want’s to get new data (a refreshed data) then he will execute new REST API call towards server.
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 software solution 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.
Authentication of REST requests
Authentication of REST request is done via tokens. One of the most common use cases is token based authentication and authorization with OAuth.