How to use the REST APIs?

Overview

Let's see how a REST request is constructed and used.

Basic components of a REST request

There are two basic steps to making a request to the REST API:

1. Request: The client accesses a specific location in her REST API and specifies the method to execute. This is known as a request.
2. Response: The server executes the method and returns data to the client. This is called a response. This process has four main components:

• Endpoint: The location of a specific resource.
• Headers: Meta information about the request or response. Specify authorization, the type of data contained in the body, and so on.
• Method: The type of interaction performed on the resource. A REST API can provide methods for creating, reading, updating, and deleting resources.
• Data (or Body): Contains the data payload sent to or received from the server. Let's take a closer look at each of these components.

Endpoints

REST APIs use Uniform Resource Identifiers (URIs) to create addresses for resources. The endpoint (or route) is the URI that’s requested; for REST APIs this is typically a URL, much like you would use in the web browser. For example, here is the URL for an endpoint on the Open Notify API that provides information about astronauts that are currently in space:

http://api.open-notify.org/astros.json

{
  "number": 10,
  "people": [
    {
      "name": "Oleg Artemyev",
      "craft": "ISS"
    },
    {
      "name": "Denis Matveev",
      "craft": "ISS"
    },
    {
      "name": "Sergey Korsakov",
      "craft": "ISS"
    },
    {
      "name": "Liu Yang",
      "craft": "Tiangong"
    }
  ],
  "message": "success"
}

If you click that link, you should see a response in JSON format that lists data about these astronauts, at the time of this article there are three people on a historic trip to the International Space Station (ISS):

Endpoints can also accept query parameters that modify the request to support additional functionality. To include query parameters, you need to add a question mark to the end of the resource URL followed by a list of key-value pairs. If you want to include multiple query parameters, you need to separate them with an ampersand. The next endpoint example accepts two query parameters to represent latitude and longitude, and returns timestamps for when ISS will pass over that point on the earth.

http://api.open-notify.org/iss-pass.json?number=10

In the above link, you can see "?" represent the starting point for query parameters. Here we have Asked the API for number 10 data.

Headers

Headers contain all of the metadata associated with the request, including information about the request and response body, authorization, caching information, and related cookies. There are numerous possible headers; here are some of the more common headers you’ll encounter while working with REST APIs:

• Content-Type: This indicates the media type that is contained in the response body and is used to inform the client about how to process it.
• Authorization: This is included in the request, and it contains the credentials that are used to access a specific resource. Authorization methods will be covered in more detail later.
• WWW-Authenticate: The server includes this in the response header when the client attempts to access a resource that requires authorization. This is often accompanied by a 401 unauthorized error, which is covered in detail later in this article.
• Cache-Control: This allows both the client and server to define caching policies, which helps reduce latency and network traffic. However, the client can only set the caching policies to whatever the server supports, so this field is important for both requests and responses.

Methods

The method is the type of request the client sends to the server. The most commonly used REST methods are GET, POST, PUT, PATCH, and DELETE:

• GET: Read a resource from a server. When a client performs a GET request, the server looks for the requested data and sends it back to the client if possible. This is the default request method.
• POST: Create a new resource on a server. When a client performs a POST request, the server creates a new entry in the database and informs the client whether the creation was successful.
• PUT and PATCH: Update an existing resource on a server. When a client performs a PUT or PATCH request, the server updates an entry in the database and informs the client whether the update was successful.
• DELETE: Delete a resource from a server. When a client performs a DELETE request, the server deletes an entry in the database and informs the client whether the deletion was successful.

Body

The body contains the data payload that is either sent to or received from the server. A REST body can contain virtually any media type, but the most commonly used media type is application/json.

How to test REST APIs?

There are a few REST API testing tools that can be used to determine whether a REST API is fully developed and ready for use, such as Advanced Rest Client, Postman-Rest Client, and Curl in Linux.

• Step #1 – Enter the URL of the API in the textbox of the tool.
• Step #2 – Select the HTTP method used for this API (GET, POST, PATCH, etc).
• Step #3 – Enter any headers if they are required in the Headers textbox.
• Step #4 – Pass the request body of the API in a key-value pair.
• Step #5 – Enter the required content type (such as application or JSON).
• Step #6 – Click the send button.

After clicking Send, there will be various responses to the REST API, which details whether the API testing was a success or failure. It’s important to note the response code, response message, and response body.