Guide 2: Understanding APIs

An API acts as a bridge that allows two applications to communicate. It sends and receives data in a structured way so systems can work together smoothly.

Why does API Matter?

• Connects ApplicationsAPIs (Application Programming Interfaces) enable two software applications to communicate easily.
• Acts as a Bridge It lets one app access features or data from another.
• Saves Time No need to build everything from scratch – speeds up development.
• Reusable Useful for repeated tasks and accessible to authorized users.
• Business-Friendly Simplifies connections with other software and third-party tools.

APIs enable smooth communication between software applications. The client sends a request to the server, which retrieves data from external sources and returns it. APIs can also trigger functions, transfer information to servers, and provide real-time updates, making them essential for modern software interaction.

An API client can be a user or an event from another app or service that starts a request when triggered. It hides complex backend details, making it easy for users to interact with.

Let’s use a food delivery app as an example to understand an API client.
You open a food delivery app like Zomato or Uber Eats to order food. The app on your phone acts as the API client. When you search for restaurants or place an order, the app sends a request to the food delivery platform’s server. The app hides all the technical complexity, like checking restaurant availability, calculating delivery fees, or processing payments. The API retrieves the required information, like restaurant menus or your order status, and presents it in a simple and user-friendly way.

Here, the API client (the app) makes it easy for you to interact with the system without worrying about how the backend works, just like ordering food without knowing how the kitchen operates.

A unique alphanumeric passcode that provides access to an API.

Purpose of API Keys
API keys help manage and secure API usage by:

1. 1. Authentication:Controlling what the user or app can do (e.g., allowing only read access).r billing or analytics).
   2. Authorization:Controlling what the user or app can do (e.g., allowing only read access).
   3. Rate Limiting:Limiting the number of API requests (e.g., 50 requests per day for free users).
   4. Usage Tracking:Identifying which app is using the API (e.g., for billing or analytics).

Security: Keeping the API safe from unauthorized access, ensuring only verified users interact with resources.

An API Request is a message sent to an application’s server for information or a service.

We commonly use Representational State Transfer (REST) APIs, so let’s explore what makes up a REST API request. The components or parameters of an API request include:

The endpoint is the URL that directs the request to a specific resource or data on the server.

Example

1. Weather API

https://api.weather.com/v1/current: This endpoint gives you the current weather information for a location.

2. User Profile API

https://api.example.com/users/12345: This endpoint retrieves details about the user with ID 12345.

3. Payment Gateway API

https://api.paymentgateway.com/v1/transactions: This endpoint processes a new transaction, allowing users to make payments.

Request methods specify the actions the client wants to perform on the URL resource. REST APIs use HTTP methods to carry out the following actions:

GET – retrieves data from a server

Example

https://api.example.com/users/12345

In this example, the GET request asks the server to retrieve information about the user with ID 12345 from the users endpoint.

POST — sends data to a server to create something, like adding a new user or saving information.

Example

https://api.example.com/users

In this example, the POST request sends data to the server to create a new user with the provided name, email, and password. The server will process this information and, if successful, create a new user in the system.

PUT — sends data to update an entire existing resource on the server. For example, it can replace all the details of a user profile.

PATCH — sends data to update only part of an existing resource. For instance, it can change just the user’s email without affecting other profile details.

This PATCH request updates only the email for user ID 4321, leaving other details unchanged.

DELETE –Tells the server to remove a specific resource, like deleting a user account.

This DELETE request removes the user with ID 4321 from the server.

Parameters are variables you pass to an API endpoint to give specific instructions to the server. They can be added in two ways: in the URL query string( after “?”) or in the request body.

Query Parameters in URL:

• Example: Searching for restaurants by location and cuisine.
• Endpoint: https://api.foodfinder.com/v1/restaurants?location=Paris&cuisine=Italian
• Explanation: The parameters location=Paris and cuisine=Italian tell the server to find Italian restaurants in Paris.

Path Parameters in URL:

• Example: Getting information on a specific movie by its ID.
• Endpoint: https://api.movies.com/movies/9876
• Explanation: Here, 9876 is the movie ID, which tells the server to return details     about the movie with that specific ID.

Parameters in Request Body:

• Example: Posting a new comment on a blog post.
• Endpoint: https://api.blogplatform.com/posts/123/comments
• Request Body:


{
"username": "john_doe",
"comment": "Great article on API usage!",
"timestamp": "2024-11-08T10:30:00Z"
}


Explanation: The parameters username, comment, and timestamp in the body provide the information needed to post a new comment on blog post ID 123.

Headers

Request headers are key-value pairs sent along with an API request to provide additional information to the server. They help the server understand the context of the request, such as what type of data is being sent, how the request should be handled, or which user is making the request.

Here are some common types of request headers:

Content-Type: Specifies the type of data being sent in the request body (e.g., JSON, XML, form data).

Example: Content-Type: application/json

Authorization: Provides authentication information, usually in the form of a token or credentials.

Example: Authorization: Bearer <your_token_here>

Accept: Tells the server what kind of response the client is willing to accept.

Example: Accept: application/json

This header indicates that the client wants the server to respond with data in JSON format.User-Agent: Identifies the client software making the request (e.g., a web browser or mobile app).

Example: 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

This header helps the server identify which browser or app is making the request, which can affect how the response is structured.

Cache-Control: Specifies caching instructions for the request.

Example: Cache-Control: no-cache

This header tells the server not to use a cached response and to fetch a fresh one.

An API server is software that lives on a server and acts as a bridge between a client (like a user’s application) and the data source. Here’s how it works:

Client Sends a Request: When a client makes an API request, it’s sent to a specific point, called an endpoint, on the API server.

Server Processes the Request: The API server receives the request, verifies who is making it (authentication), checks that the data is correct, and then gets or changes the necessary data from a database.

Server Sends a Response: Finally, the API server sends the right response back to the client.

In simple terms, the API server’s job is to handle requests from the client, make sure they’re valid, interact with the database, and return the correct information.

When an API server receives a request from an API client, it sends back an API response. The response provides important information about what happened with the request. Here’s what it includes:

Status Code

The status code shows the client if the request was successful or not. For example:

• Code 200 means the server successfully returned the requested data.
• Code 201 means the server successfully created a new resource.
• Code 404 (which we often see) means “Not Found,” indicating the server couldn’t find what was requested.

Response Headers

Response headers give extra information about the server’s response. They might include details like:

• Cache-Control: Tells the client how long it can store (or cache) the data.
• Set-Cookie: Sets a cookie for things like managing sessions or logging in.

Body

The response body holds the actual data from the server based on what the client requested. This might include things like structured data, extra details about the resources, or error messages if something went wrong with the request.