A Quick Guide to REST Documentation

If you’re reading this you have probably already seen the words REST API mentioned, most likely when you have tried to retrieve data from an internet source such as Twitter. But do you actually know what REST API means? What exactly is a REST API and how can it help you? 

In this short article, Stoplight will take you through the background to REST – what it means, how you can use it, and when you use it – and give details on REST documentation and what you need to consider. Take a look at this quick guide and discover the key points that will make your REST documentation journey easier.

What is an API?

API stands for Application Programming Interface and it is basically an interface that acts between two different computer systems and allows them to interact. So, when you press a command on an interface there are functions beneath the interface that act to find the necessary information. But because these functions need to find the information from another place on the web, they need the “cog” of the API in order to do so. 

REST API: Definition

Starting with the basics, the REST API is a simple concept. REST Stands for Representational State Transfer, which may or may not mean a great deal to you. It basically comprises certain rules which need to be followed when a developer creates an API. A specific rule is that a resource (a piece of data) should be able to be retrieved when a developer links to a URL. In essence, REST formulates how the API will look. 

For example, if you are looking on YouTube for videos about kittens, you type “kittens” into the search bar and you get a list of kittens videos. The REST API follows a similar pattern but it is used inside a service. 

Style or Standard?

Like SOAP before it, REST uses HTTP for carrying out the message retrieval and response transportation. But REST differs from SOAP in that it is a style and not a standard. Sometimes REST APIs are termed RESTful APIs, which implies that the REST is not standard protocol but the style which the API follows. REST APIs may use any of the message formats available like RSS, HTML, or XML. This depends on developer preference, although in reality, most REST APIs make use of the JSON message format as standard. This is because this format is lightweight and straightforward – it is simple and flexible. Therefore, it is ideally suited to mobile apps.  

Other Features of REST APIs

A REST API is typically focused on “things”, instead of “actions”. In general, they deal with resources and the ways in which resources are accessed. These resources are made up of different information and are accessed through URLs. Just like when you access a URL on the web, these URLs are paired with a method that sets out the interaction with the resource. For example, there are POST (create), DELETE (remove) and GET (read) methods. In essence, the web follows the REST style.