Introduction to Rest API

5 min readJun 28, 2024

APIs (Application Programming Interfaces) are sets of rules and protocols that allow different software applications to communicate with each other. They play a crucial role in modern software development by enabling the integration of different systems and services. Here are some key aspects of APIs:

Endpoint: A specific URL where an API can access resources.
Request Body: Contains data sent to the API, typically used with POST or PUT requests.
Method: The type of request (e.g., GET, POST, PUT, DELETE).
Response Body: Data returned from the API.
Headers: Provide additional information to the server.

API Server: The server receives the request and processes it. The server is responsible for handling the logic of the application, such as querying the database, performing calculations, and applying business rules.

API Authentication: To access the server, API clients must be authenticated. e.g. To access your instagram account one need to login with their Username and Password which returns an access token to be used by the all other feature end points in app like getting feed, followers , grid pictures, stories etc.

API Key: A simple token passed in the request header.
OAuth: A more secure method involving token-based authentication and authorization.
more detailed info on Authentication:

Database:

The API server interacts with the database to store or retrieve data. The database can be any type of data storage system, such as SQL, NoSQL, or other data storage solutions

API Components:

End Point

```{{Protocol}}/{{API-Server-URL}}/{{Version}}/{{End Point}}````

Syntax Breakdown:

{{Protocol}}: This indicates the protocol used to communicate with the API. Commonly, it will be http or https (the latter being more secure).
{{API-Server-URL}}: This is the base URL of the server where the API is hosted. It typically includes the domain name and any necessary subdomains.
{{Version}}: This denotes the version of the API being accessed. Versioning helps manage changes and backward compatibility.
{{End Point}}: This specifies the specific resource or action you want to interact with on the API.

Hypothetical example: get List of followers

https://www.instagram.com/v1/list-followers

Method:

In the context of APIs, particularly RESTful APIs, the “method” refers to the HTTP method used to interact with the resources. {{Get,Post, Put, Patch, Delete}} are the main methods used by Rest.

How HTTP Methods Work is :

GET requests are read-only and do not alter the state of the resource.
Example: Fetch a list of followers.

response = requests.get(“https://www.instagram.com/v1/list-followers")```

POST requests are used to create new resources and may alter the server’s state.
Example: Create a new post.

data = {‘content’: ‘New post content’}
response = requests.post(“https://www.instagram.com/v1/posts", data=data)

PUT requests update the entire resource and may also create a resource if it doesn’t exist.
Example: Update user profile information

data = {‘username’: ‘new_username’}
response = requests.put(“https://www.instagram.com/v1/users/12345", data=data)```

DELETE requests remove a resource and alter the server’s state.
Example: Delete a specific post using post-id e.g 67890 is the post id from data-Record

response = requests.delete("https://www.instagram.com/v1/posts/67890")

PATCH requests partially update a resource, making it more efficient for changes to only part of the data.
Example:Update part of a user profile (e.g., change the bio).

data = {'bio': 'Updated bio'}
response = requests.patch("https://www.instagram.com/v1/users/12345", data=data)

Headers:

Headers in HTTP requests and responses are key-value pairs sent between the client and server. They provide additional information about the request or response, such as metadata, and control how the client and server should handle the request or response. Here’s a detailed breakdown:

Example Request and Response Headers

HTTP Request:

GET /api/users HTTP/1.1
Host: www.example.com
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36
Accept: application/json
Authorization: Bearer token12345
Accept-Language: en-US,en;q=0.9

HTTP Response:

HTTP/1.1 200 OK
Date: Wed, 30 Jun 2021 12:28:53 GMT
Content-Type: application/json
Content-Length: 1234
Server: Apache/2.4.41 (Ubuntu)
Set-Cookie: sessionId=abc123; Path=/; HttpOnly
Cache-Control: no-cache, no-store, must-revalidate

{
    "users": [
        {
            "id": 1,
            "name": "John Doe"
        },
        {
            "id": 2,
            "name": "Jane Smith"
        }
    ]
}

Response Body:

when a client makes a request to an API, the server processes that request and sends back a response. This response typically consists of three main parts:

Status Code: Indicates the status of the request (e.g., 200 OK, 404 Not Found).
Headers: Provide metadata about the response (e.g., content type, content length). — Refer to Headers Section for details
Body: Contains the actual data being sent from the server to the client. This is what we refer to as the “API response body.”.

Examples of Response Code:

200 OK: The request was successful, and the server is returning the requested data e.g List of followers in followers list.
201 Created: The request was successful, and a new post was created.
401 Not Authorized: appears when username/password is incorrect.
404 Not Found: The requested resource was not found on the server. when nothing is found in your search criteria.
500 Internal Server Error: There was an error on the server while processing the request. some criteria is not met
502 Server Communication Error: Server is failing to communicate to the client

Examples of Response body:

The response body can be in various formats, the most common being JSON (JavaScript Object Notation) and XML (Extensible Markup Language). JSON is widely preferred due to its simplicity and ease of use with JavaScript.

{
  "status": "success",
  "data": {
    "userId": 12345,
    "name": "John Doe",
    "email": "john.doe@example.com"
  },
  "message": "User data retrieved successfully"
}

In conclusion, the significance of understanding API workflows cannot be overstated. It is a skill that not only enhances a developer’s toolkit but also drives innovation and connectivity in the digital age.