Lesson 5 of 31
In Progress

REST API : Basics and How to Use it

August 29, 2020

In this article, you’ll learn everything you need to know about REST APIs to be able to read API documentations and use them effectively.

API

An API is an application programming interface. It is a set of rules that allow programs to talk to each other. The developer creates the API on the server and allows the client to talk to it.

  1. SOAP
  2. REST

SOAP

SOAP is a standard communication protocol system that permits processes using different operating systems like Linux and Windows to communicate via HTTP and it is mainly XML.

REST

REST determines how the API looks like. It stands for “Representational State Transfer”. It is a set of rules that developers follow when they create their API. One of these rules states that you should be able to get a piece of data (called a resource) when you link to a specific URL. Rest is also communicated via HTTP.

Each URL is called a request while the data sent back to you is called a response.

Breakdown of A REST – Request

It’s important to know that a request is made up of four things:

  1. The endpoint
  2. The method
  3. The headers
  4. The data (or body)

1. The Endpoint

The endpoint (or route) is the url you request for. It follows this structure:

root-endpoint/path?queryparameters

root-endpoint

The root-endpoint is the starting point of the API you’re requesting from. For example

https://www.api.github.com/

path

The path determines the resource you’re requesting. For example given the url https://www.api.github.com/users/:username/repos where https://www.api.github.com/ is the root-endpoint and /users/:username/repos is the path.

Any colons (:) on a path denotes a variable. You should replace these values with actual values of when you send your request. In this case, you should replace :username with the actual username of the user you’re searching. for.  example:

/users/testuser/repos

query parameters.

Query parameters give you the option to modify your request with key-value pairs. They always begin with a question mark (?). Each parameter pair is then separated with an ampersand (&), like this:

?query1=value1&query2=value2

End to end endpoint for REST API will look like:

https://api.github.com/users/zellwk/repos?sort=pushed

Test End Point with CURL command

curl https://api.github.com/users/zellwk/repos\?sort=pushed

2. The Method

The method is the type of request you send to the server. You can choose from these five types below:

  • GET
  • POST
  • PUT
  • PATCH
  • DELETE
Method NameRequest Meaning
GETThis request is used to get a resource from a server. If you perform a GET request, the server looks for the data you requested and sends it back to you. In other words, a GET request performs a READ operation. This is the default request method.
POSTThis request is used to create a new resource on a server. If you perform a POST request, the server creates a new entry in the database and tells you whether the creation is successful. In other words, a POST request performs an CREATE operation.
PUT and PATCHThese two requests are used to update a resource on a server. If you perform a PUT or PATCH request, the server updates an entry in the database and tells you whether the update is successful. In other words, a PUT or PATCH request performs an UPDATE operation.
DELETEThis request is used to delete a resource from a server. If you perform a DELETE request, the server deletes an entry in the database and tells you whether the deletion is successful. In other words, a DELETE request performs a DELETE operation.

Example:

GET /users/testuser/repos

3. The Headers

Headers are used to provide information to both the client and server. It can be used for many purposes, such as authentication and providing information about the body content.

You can send HTTP headers with curl through the -H or --header option. To send the above header to Github’s API, you use this command:

curl -H "Content-Type: application/json" https://api.github.com

4. The Data (Or “Body”)

The data (sometimes called “body” or “message”) contains information you want to be sent to the server. This option is only used with POSTPUTPATCH or DELETE requests.

To send data through cURL, you can use the -d or --data option:

curl -X POST  -d property1=value1 -d property2=value2

If you wish to send JSON data, you’ll need to set the Content-Type to application/json, and you’ll need to format your data as a JSON object, like this:

curl -X POST https://requestb.in/1ix963n1 \
  -H "Content-Type: application/json" \
  -d '{
  "property1":"value1",
  "property2":"value2"
}'

Response

Depending on the Content-Type in the header the response will differ. For example the response with application/json will have a json response.

Sample JSON response:

[
  {
    "id": 1296269,
    "name": "Hello-World",
    "full_name": "octocat/Hello-World",
    "owner": {
      "login": "testuser",
      "id": 1
    },
    "topics": [
      "octocat",
      "atom",
      "electron",
      "api"
    ]
  }
]

Authentication

Since POSTPUTPATCH and DELETE requests alter the database, developers almost always put them behind an authentication wall. In some cases, a GET request also requires authentication

Ways to Authenticate

  1. With a username and password (basic authentication)
  2. With a secret token

1. Basic Authentication (With Username and Password)

To perform a basic authentication with cURL, you can use the -u option, followed by your username and password, like this:

curl -x POST -u "username:password" https://api.github.com/user/repos

2. With a Secret Token

The secret token method includes oAuth, which lets you to authenticate yourself with social media networks like Github, Google, Twitter, Facebook, etc.

HTTP Status Codes And Error Messages

They only appear when something is wrong with your request. HTTP status codes let you tell the status of the response quickly. 

Status CodeMeaning
200+Succeeded
300+Redirected to another URL
400+Error that originates from the client
500+Error that originates from the server

API Versions or Versioning

 The API can change so much that the developer decides to upgrade their API to another version.  You can request for a specific API version in two ways. Which way you choose depends on how the API is written.

These two ways are:

  1. Directly in the endpoint
  2. In a request header

1. Directly in the endpoint

At the time of writing, Twitter’s API is at version 1.1, which is evident through its endpoint:

https://api.twitter.com/1.1/account/settings.json

2. In the request header

At the time of writing, Github’s API is at version 3, and you can specify the version with an Accept header:

curl https://api.github.com -H Accept:application/vnd.github.v3+json

Source: SmashingMagazine