Let’s say you’re trying to find videos about Batman on youtube. You open up youtube, type “Batman” into a search field, hit enter, and you see a list of videos about Batman. A REST API works in a similar way. You search for something, and you get a list of results back from the service you’re requesting from.

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.

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.

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

JSON

JSON (JavaScript Object Notation) a common format for sending and requesting data through a REST API. The response that Github sends back to you is also formatted as JSON.

A JSON object looks like a JavaScript Object. In JSON, each property and value must be wrapped with double quotation marks, like this:

{
"property1": "value1",
"property2": "value2",
"property3": "value3"
}

Methods of REST API

The method is the type of request you send to the server. It is used to perform four possible actions: Create, Read, Update and Delete (CRUD).

GET

This 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.

POST

This 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

This request is used to update a resource on a server. If you perform a `PUT` request, the server updates an entry in the database and tells you whether the update is successful. In other words, a `PUT`request performs an `UPDATE` operation.

DELETE

This 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.

Authentication

You wouldn’t allow anyone to access your bank account without your permission, would you? On the same line of thought, developers put measures in place to ensure you perform actions only when you’re authorized to do. This prevents others from impersonating you.

Since POST, PUT, PATCH and DELETE requests alter the database, developers almost always put them behind an authentication wall. In some cases, a GET request also requires authentication (like when you access your bank account to check your current balance, for example).

On the web, there are two main ways to authenticate yourself:

  1. With a username and password (also called basic authentication)
  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.

Now, let’s talk about HTTP Status codes and error messages.

HTTP Status Codes And Error Messages

Some of the messages you’ve received earlier, like “Requires authentication” and “Problems parsing JSON” are error messages. They only appear when something is wrong with your request. HTTP status codes let you tell the status of the response quickly. The range from 100+ to 500+. In general, the numbers follow the following rules:

  1. 200+ means the request has succeeded.
  2. 300+ means the request is redirected to another URL
  3. 400+ means an error that originates from the client has occurred
  4. 500+ means an error that originates from the server has occurred