A Step-by-Step Tutorial: Mastering API Calls for Beginners

What is API Hitting?

API hitting refers to the conversation happening between your application and a web service. The intricacies of API hitting revolve around these technical aspects.

API Hitting Details

Parties involved:

• Your Application: This is the program that initiates the communication, acting like a curious customer seeking information or functionality.
• The API: This is the interface provided by a web service, working like a restaurant's menu that outlines available options and how to order them.
• The API Server: This is the backend system that processes requests and sends responses, acting as the kitchen that fulfills orders based on the menu.

Conversation between application and web service:

A typical conversation between an application and a web service has a few steps, which are:

1. Finding the Menu (API Documentation):

The application doesn't blindly send requests. It first consults the API documentation, which serves as the instruction manual. This document explains:

• Endpoints: Specific URLs that act like designated sections on the menu, each offering particular functionalities (e.g., /users for user management, /products for product details).
• Request Methods: Verbs like GET (to retrieve data), POST (to send data), PUT (to update data), and DELETE (to remove data) –indicate the desired action, similar to how you tell the waiter what you want (e.g., GET /users to retrieve a list of users).
• Parameters: Additional information you might need to include, like specifying a user ID when fetching details (e.g., GET /users/123 to get information about the user with ID 123).
• Headers: Extra data sent along with the request, often for authentication (like an API key) or specifying data format (e.g., JSON).
• Response Formats: The format of the data you'll receive back (JSON, XML, etc.), akin to how your order confirmation might come on a receipt.

2. Crafting the Request (Building the Order):

Based on the API documentation, your application constructs a request message. This message typically includes:

• URL: The specific endpoint relevant to the desired action.
• Method: The HTTP method indicates what you want to do (GET, POST, etc.).
• Headers: Any necessary authentication details or data format specifications.
• Body (for POST, PUT): The actual data you're sending to the server, formatted according to the API's requirements (often JSON). This could be new user information for creating an account or product details for an update.

3. Sending the Request (Placing the Order):

Your application transmits the crafted request message to the API server. Imagine sending your order to the kitchen through a waiter.

4. Processing the Request (Fulfilling the Order):

The API server receives the request and interprets it based on the endpoint, method, and any parameters included. It then performs the requested action:

• For a GET request, it retrieves data from its database.
• For a POST request, it creates a new entry based on the provided data.
• For a PUT request, it updates existing data.
• For a DELETE request, it removes data.

5. Sending the Response (Delivering the Order):

The server processes the request and generates a response message. This response typically includes:

• Status Code: A numeric code indicating success (e.g., 200 for OK) or an error (e.g., 404 for Not Found).
• Headers: Additional information like content type or rate limits.
• Body: The actual data retrieved, created, updated, or confirmation of deletion, formatted according to the specified response format.

6. Parsing the Response (Checking Your Order):

Your application receives the response message and interprets it based on the API documentation. It extracts the relevant information:

• For a successful response, it retrieves the requested data or confirmation message.
• For an error response, it identifies the error code and message to understand the issue and handle it gracefully (e.g., informing the user or retrying the request later).

Real-world Examples of API Hitting

Here are a few real-world situations where you can see API hitting working in practice!

Scenario 1: Weather App

• Your Application: A weather app that displays current conditions and forecasts.
• The API: A weather service API like OpenWeatherMap (https://openweathermap.org/api).

1. Request: Your app constructs a GET request to the OpenWeatherMap API endpoint for current weather data in your user's location. It includes the user's latitude and longitude as parameters.
2. Response: The API server retrieves weather data from its database based on the location and sends a response containing the current temperature, humidity, wind speed, etc., formatted in JSON.
3. Parsing the Response: Your app parses the JSON response, extracts the relevant weather data, and displays it to the user.

Scenario 2: E-commerce Platform

• Your Application: An e-commerce platform that allows users to add products to their carts.
• The API: An internal product catalog API.

1. Request: When a user adds a product to their cart, your application makes a POST request to the product catalog API endpoint. The request body includes the product ID and quantity.
2. Response: The API server checks the product availability and inventory. If successful, it sends a response with a confirmation message and potentially the updated cart total.
3. Parsing the Response: Your application parses the response and updates the user's cart information on the screen. It might also handle any errors returned by the API (e.g., out-of-stock product).

Scenario 3: Social Media App

• Your Application: A social media app that allows users to post updates with images.
• The API: An image hosting API like Imgur (https://apidocs.imgur.com/).

1. Request: When a user posts an update with an image, your app first uploads the image to the Imgur API using a POST request. The request body includes the image data.
2. Response: The Imgur API server uploads the image and sends a response containing the image URL.
3. Parsing the Response: Your application receives the response, extracts the image URL, and then makes another request to its social media API endpoint to create the user's post with the image URL included.

Apidog - Simple Yet Beautiful API Development for API Analysis

To view API hitting in detail, it is best to utilize an API tool that allows you to view the responses of an API. Once you can see the structure of the API response, you can then modify your application's code so that it can process the incoming data. A perfect API tool for this job would be Apidog, an all-in-one API platform.

Viewing an API Response Using Apidog

What you want in an API tool is a simple yet easy-to-understand user interface. Designed with a straightforward format, you can quickly understand what details and functionalities Apidog provides its users. Moreover, you can test out APIs on the go, viewing the different API responses codes that you may encounter when communicating with the API.

From the image above, you can easily view the response that the API sent back to you, the client. With a clear image of what the API returns to your application, you can then confidently design your code without having to second-guess yourself, saving precious time and effort.

Conclusion

Hitting an API unlocks a world of possibilities for applications. It establishes a communication channel between your program and external web services, enabling you to retrieve data, perform actions, and integrate functionalities that would be cumbersome to develop from scratch. This allows you to focus on your application's core features while leveraging the expertise and resources of other services.

By understanding the technical aspects and following best practices for hitting APIs, you can create powerful and dynamic applications that seamlessly connect to the vast ecosystem of web services available today.