Imagine you’re a customer (client) at a restaurant. The waiter (API) functions as an intermediary between you and the kitchen (web server). The menu (set of rules) which gives you specifically what you can order is handed over to you. You tell the waiter your order (you make a request), and the waiter requests it from the Chef (Web server) who gets the necessary ingredient (Database) he has access to and Finally, the waiter will provide you with what you ordered (response). The waiter is the intermediary between you and the kitchen. In this metaphor, the waiter is effectively an abstraction of the API. In this example, as a customer (client), you don’t need to know how the kitchen or the restaurant operates in order to get what you want: the food. You just need to know what to order and how to order it.

API stands for “application programming interface.” It is a set of rules that allow programs to talk to each other. Most web APIs sit between the application and the web server. The user initiates an API call that tells the application to do something, then the application will use an API to ask the web server to do something.

The API is the middleman between the application and the web server, and the API call is the request. And every time you use software to communicate with other software or online web servers, you’re using APIs to request the information you need. API creates an object of the data requested by the client and thereafter sends the values of the object in response to the client requests. Common types of APIs are REST APIs, SOAP APIs, Browser APIs, Android /iOS APIs. Our focus in this article is mainly the REST APIs.

REST APIs

REST meaning Representational State Transfer is a type of software design that gives access to data (aka “web resources”) by using a uniform and predefined set of operations. REST determines how the API looks like. It is the 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(response) when you link to a specific URL (request).

THE ANATOMY OF A REQUEST

A request is made up of four things:

• THE ENDPOINT

  There are two key parts to an endpoint(route) that are used when making an API request. One of which is the URL you request for. The second part is the path. The path will vary depending on what resource you’re requesting for. For example: https://api.libraryup.com/books/:book_id/.

https://api.libraryup.com is the root-end point WHILE /books/book_id is the path.

The root-endpoint is the starting point (URL) of the API you’re requesting from. The path determines the resource you’re requesting for.

Note: Any colons (:) on a path denotes a variable. You should replace these values with actual values(say book_id) of when you send your request. For example, You can search a book with id of 1 by searching https://www.libraryup.com/books/1.

To understand what paths are available to you and how to use them, you need to look through the API documentation.

JSON

JSON (JavaScript Object Notation) a common format for sending and requesting data through a REST API. The response that Libraryup sends back to you is also formatted as JSON. In JSON, each property and value must be wrapped with double quotation marks, like this:

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

METHOD

The method is the type of request you send to the server. These methods provide meaning for the request you’re making. They are used to perform four possible operations: Create, Read, Update and Delete (CRUD).

• GET: This request is used to get/retrieve 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. This is the default request method and it is READ only.

• POST: This request is used to create/send a new data/resource on a server. f you perform a POST request, the server accepts the data enclosed in the body of the request message, then creates a new entry in the database. It is often used when uploading a file or when submitting a completed web form.

• PUT: This method is used in modifying resource where the client sends data that updates the entire resource. It is used to set an entity’s information completely. PUT is similar to POST in that it can create resources, but it does so when there is a defined URI. PUT overwrites the entire entity if it already exists, and creates a new resource if it doesn’t exist.

• PATCH: Unlike PUT, PATCH request applies a partial update to the resource. This means that you are only required to send the data that you want to update, and it won’t affect or change anything else.

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

The API let you know what request method to use when making an API call. For example, to get a list of all Library books, you need a GET request:

GET  /books/1

A GET request is required to get a book with id of 1 from the library. To add(create) a new book in the library, you need a POST request:

POST /books

HEADERS

Headers are used to provide information to both the client and server. HTTP Headers are property-value pairs that are separated by a colon. It can be used for many purposes, such as authentication and providing information about the body content which informs the server about what type of content will be sent.

For example, a commonly used content type is “application/json” which let’s the server know, we are sending JSON data across. The example below shows a header that tells the server to expect JSON content.

"Content-Type: application/json". Missing the opening ".

You can find a list of valid headers on MDN’s HTTP Headers Reference.

and the last part of a request is:

The Data (Or “Body”):

The data (sometimes called “body” or “message”) contains information you want to be sent to or returned by the server. This option is only used with POST, PUT, PATCH or DELETE requests. In the previous discussion of JSON, you can see an example of API data. The body of a request will sometimes require specific information before it can be delivered. An example of this is if you are editing a single product, the Product ID will be required before any change can be made.

However, In order to perform a request both on local server and web-based server, Postman, an API testing application can be used to perform a request with GET, POST, PUT, PATCH and DELETE methods on APIs you create yourself. You can download postman here to get started.

Authentication

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 perform authentication:

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

When something is wrong with your request, for example, an authentication error. 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:

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

Wrapping Up

In this article, you learned what an API, a REST API are. I hope this article has helped you learn enough about REST APIs, and you can use them fluently as you create your applications. Feel free to pop over to my blog or leave your comments below if you have any questions.

Thanks for reading!

Cheers!