Gichuki EdwinAPIs are essential tools that allow servers to communicate with one another. Whether you’re building a frontend that interacts with a backend or fetching data from an external server, understanding how to structure API requests is crucial. Let’s break down the key concepts—endpoints, path parameters, and query parameters—using the ISS Tracker API as a practical example.
What is an API?
At its core, an API (Application Programming Interface) allows two applications to communicate with each other. When your frontend sends a request to your backend (such as loading a page), you're essentially calling a private API because it's not publicly documented or accessible to others. However, when you interact with services like the ISS tracker, you’re using a public API, which is openly documented for external use.
Key Concepts for Structuring API Requests
1. Endpoints
An endpoint is the specific address where your API request is directed. It’s essentially a route on the server that tells the API what kind of data you want to fetch or what action you want to perform. Endpoints usually come after a base URL and are defined based on the functionality they provide.
For example, in the ISS Tracker API, the base URL might look like this, https://api.wheretheiss.at/v1
Let’s say you want to get the current location of the International Space Station. You’d hit the /satellites endpoint like this, https://api.wheretheiss.at/v1/satellites/25544
Here, 25544 is the unique identifier for the ISS, making this a path parameter. The endpoint /satellites/25544 fetches the current location data of the ISS.
2. Path Parameters
Path parameters are dynamic values included in the URL itself. They help specify exactly which resource you want to retrieve. In our ISS example, 25544 is the specific satellite ID for the ISS. The structure here looks like this https://api.wheretheiss.at/v1/satellites/{satellite_id}
If you wanted to track a different satellite, you’d replace 25544 with the corresponding satellite ID in the URL.
However, the 'Where the ISS at?' API currently has information for only one satellite, the International Space Station.
By using path parameters, you allow for more flexibility in accessing specific resources through a single endpoint. For example, in the ISS API:-
/satellites/25544 gives you the ISS location.
/satellites/{satellite_id} would give you data for another satellite if you provide a different satellite ID.
3. Query Parameters
Query parameters add more filtering options to your requests, allowing you to pass additional data to refine your search or request. Query parameters are added to the URL after a question mark (?) and usually come in key-value pairs separated by an equal sign (=).
For example, you can get more specific with the ISS API by requesting data for a particular timestamp. Let’s say you want to know the ISS location at a specific point in time, https://api.wheretheiss.at/v1/satellites/25544/positions?timestamps=1627044124
Here, the query parameter is timestamps=1627044124, where timestamps is the key, and 1627044124 is the value representing a specific UNIX timestamp. You can also add multiple query parameters by using an ampersand (&) to separate them. For example, https://api.wheretheiss.at/v1/satellites/25544/positions?timestamps=1627044124&units=miles
This query requests the ISS location data for a specific timestamp and specifies that the distance should be returned in miles.
Structuring API Requests in Practice
Let’s break down the process of structuring an API request using the ISS Tracker API in the steps below:
-
Base URL - The root domain that points to the server. For the ISS Tracker API, the base URL is,
https://api.wheretheiss.at/v1
Endpoint - Determines the specific data you’re requesting. For example, to get the current ISS location, use: /satellites/25544
Path Parameters - The ID, 25544 fetches data for the ISS specifically. The path parameter is embedded within the endpoint and helps pinpoint specific resources.
Query Parameters - Add optional parameters to filter or modify the request. For example, you can include a timestamp or specify units (miles or kilometers):
?timestamps=1627044124&units=miles
Making API Requests in Postman
Let’s walk through a simple example using Postman:
Open Postman and create a new request.
Set the request type to GET since you're retrieving data.
Enter the following URL to get the current position of the ISS: https://api.wheretheiss.at/v1/satellites/25544
Optionally, add query parameters by navigating to the “Params” section in Postman, where you can input keys and values like:
timestamps = 1627044124, units = miles
Postman will automatically append these to the URL, and when you send the request, the ISS location data for that timestamp will be displayed.
Conclusion
Structuring API requests effectively involves understanding endpoints, path parameters, and query parameters. These concepts allow you to interact with APIs like the ISS Tracker, making your requests dynamic and flexible. Whether you’re fetching live data or querying for specific details, learning how to structure these requests is key to integrating APIs into your applications.
