Introduction to REST APIs

  • by

Web applications today have become more complex than they were during the dot com boom. Hence, various methods of building applications have come to light. These methods make it easier to keep complexity at its minimum, and make the apps maintainable. One of these methods is the REST API.

REST (Representational State Transfer), a term coined by Roy Fielding in 2000 is an architectural style and approach to communication (between the server and client) often used in developing web applications. This kind of API leverages less bandwidth, making it more suitable for internet usage compared to SOAP(Simple Object Access Protocol) APIs.

An API known in full as an Application Programming Interface, specifies how application components should interact. In the case of web applications, APIs use HTTP requests, and return responses in JSON or XML format.

Bringing both concepts together, an API is said to be RESTful if it abides by the REST concepts. In the next couple of minutes, you’ll get to learn about these concepts, see how these APIs are documented and can be tested.

Common HTTP Methods

Remember that APIs use HTTP requests? Well, HTTP requests are basically the same thing as HTTP methods. The most common HTTP methods are:

  • POST (Create)
  • GET (Read)
  • PUT (Update)
  • DELETE (Delete)
  • PATCH (Partial Update)

Together, these methods are known as CRUD method. Here’s a brief look into each of them and what they mean.


The POST method is used to create or append resource to the server. It responds with status code 201(created), which implies that a resource has been created.


The GET method is used to request a resource from the server. It is considered to be an idempotent request. This implies that the response to such requests will be the same always. GET requests provide a response with status code 200.


The PUT method is an idempotent used to update / modify resources on the server. Unlike with the POST method, the PUT method will update or completely replace old data, instead of creating a new one.


The PATCH method is used for making partial updates / modifications to resources on the server. Unlike PUT, PATCH only makes changes to a specific part of the resource and not all. 


The DELETE method does the opposite of the POST method. It removes resources from the server. This method is easy to comprehend as the name explains it all.

REST API Authentication Methods

APIs usually provide direct access to data hosted on the server. Hence, you won’t want everyone to be able to create, read, update or delete data. You need to limit access to certain kinds of users. The way to do this is to authenticate, forcing users to identify themselves before they can access private data. 

Authentication is closely related to authorization but different. Authentication is the act of confirming if a user or a process is what it claims to be. Authorization on the other hand is the permission given to a user or process after authentication.

There are three common methods of authentication:

  • HTTP Basic Auth
  • OAuth
  • API keys

HTTP Basic Auth

HTTP Auth is a traditional method of authentication. It requires a username and password as credentials for authentication. This method is efficient and is quite safe. However, it is susceptible to issues if users use special characters in their passwords.


OAuth is a very powerful and safe protocol for authentication. It allows third party applications like Facebook, Google and Github have access to users information without sharing passwords. 

OAuth 1.0 and 2.0 are the former and latter versions of OAuth. OAuth 2.0 is now generally accepted as the most secure for authentication. 

The common token implementation in OAuth 2.0 are:

  • Access tokens: Access tokens are used for authentication and authorization of users, and it expires over time.
  • Refresh tokens: Refresh tokens generate new access tokens when they expire.

API Keys

API keys are also another method of authenticating users. These keys are unique strings that are added to the URL or Header of a request. However, they are often added to the request Header for more security. An API key is assigned to each user, and is validated on each request made.

While API keys have been adopted by many companies. They are not yet considered to be the more secure means of implementing authentication of REST APIs. 

Why APIs Should Be Tested?

API testing is a type of software testing that performs the verification of an application’s functionality at the API level. It allows you to detect bugs during development phase before software is pushed into production. 

API testing can be done with tools like:

  • Postman 
  • Curl 
  • Advanced Rest Client

However, in this article, you’ll only learn about Postman.


Postman is a Google Chrome app built for interaction with APIs. Postman allows developers to test API endpoints without writing any code, and is quite popular for its user-friendly interface.

In this section, you’ll learn about the following:

  • Installation
  • Testing


Postman is available for Windows, Linux and Mac Operating Systems. You can also make use of it as a Google Chrome extension. Installation is easy across these platforms, as it is a click-through process where the defaults are usually sufficient for testing.


API testing with Postman is easy and straightforward. All you need is the endpoint and HTTP method for accessing the functionality to be tested. You’ll see below some tests of endpoints of a sample Todo app. The server is running locally and on port 4000.

The following methods will be illustrated:

  • GET
  • POST
  • PUT


To test a GET endpoint, do the following:

  1. Select the GET method 
  2. Type in the URL
  3. Hit the send button

The image above shows the response to the GET request. A list of available todos with a status code 200.


To test a POST endpoint, do the following:

  1. Select the POST method 
  2. Type in the URL
  3. Set Content-Type to application/json in Headers
  4. Enter body values 
  5. Hit the send button

API request body and response can be in XML or JSON. In the screenshot above, the request and response body are in JSON.


To test a PUT endpoint, do the following:

  1. Select the PUT method 
  2. Type in the URL 
  3. Set Content-Type to application/json in Headers
  4. Enter body values 
  5. Hit the send button

To update a resource (a todo in this case), it has to be selected by a specified URL. The URL here is “/todos/2”, 2 here is a unique identity to the updated todo. 


To test a PATCH endpoint, do the following:

  1. Select the PATCH method
  2. Type in the URL 
  3. Set Content-Type to application/json in Headers
  4. Enter body values 
  5. Hit the send button

In the PUT request,  “todos/2” completed status was false. Using PATCH, the completed status was updated to true. 


To test a DELETE endpoint :

  1. Select the DELETE method 
  2. Type in the URL 
  3. Enter body values 
  4. Hit the send button

In the above request, “todos/1” is selected and permanently deleted from the server.

What Is an API Documentation?

An API documentation is a well-written document which gives details of every aspect and explanation on how developer/users can utilize an API. 

Some tools for creating API documentation are:

  • Swagger
  • Dapper Dox
  • Postman

Importance of API Documentation

Documenting an API may seem boring or difficult, but it is essential. You can have a functional API, but it will be hard for a third party to use it if lacking proper documentation. Documenting your API is a way of getting people excited about your product and get them to use it.

Tips to Reading API Documentation

To have a good understanding of an API documentation, for example the Github API; it is important to understand the properties of the requests that API can accept.

Here are some key points to watch out for:

  • Endpoints
  • Methods
  • Headers 
  • Body (data)


An endpoint is the URL of a request also known as path or route. An API can have as many endpoints as possible, most APIs have a root-path which is usually “<api name>/” or locally as “localhost:<port>/”.

Columns found on paths are to be replaced with a real values. In this example: “/users/:username/repos”, “/:username” is to be replaced with a value. 

One other thing to note is the query parameter, “?”. The sign “?” is added to the end of a path to assign values to specific parameters and is separated with an ampersand (&). A typical example is: “”


We discussed the common HTTP methods. GET, POST, PUT, PATCH and DELETE .


Header contents are additional information sent to the client and server. Examples of headers include:

  • Content-Type: for specifying the request body format 
  • Authorization: contains the credentials for authorization 


    The request body is the data sent to the server. This data can be sent in formats such as JSON, Form-data and so on.

    If the anatomy of request is understood, understanding API documentation is easy.


    Today, REST APIs are commonly used when building web applications. Hence, if you are a software developer, software tester. It is great that you understand them, know how to test them and how to build them—if you are a developer.

    Hopefully, this article has served as a great introduction to REST APIs for you. You’ve learnt about the HTTP methods, means of authentication, how to test the APIs and how to work your way around documentation. Now it’s time to put this knowledge to practice and contribute to the success of amazing software products.

    Leave a Reply

    Your email address will not be published. Required fields are marked *