Understanding API Endpoints: Structure and Examples

API endpoints are one of the most fundamental concepts in working with APIs. They act as the gateways or access points through which applications interact with an API to exchange data.

What Is an API Endpoint?

An API endpoint is a specific URL that represents a unique resource or functionality provided by an API. It is where an API receives requests and sends responses. Think of it as a door to the API’s functionality that applications use to interact with the API.

For example, in a weather API, /current-weather might be an endpoint that provides current weather data for a given location.

Key Points to Remember:

Endpoints are part of an API’s base URL.
They are designed to handle specific operations, like retrieving or updating data.
Endpoints often include parameters or paths to customize the data being requested.

Structure of an API Endpoint

An API endpoint typically consists of the following components:

Base URL: The root URL of the API.
Example: https://api.openweathermap.org
Path: A specific resource or action available within the API.
Example: /data/2.5/weather
Query Parameters: Optional values to modify the request, such as location or date.
Example: ?q=London&appid=your_api_key

Complete Example:

https://api.openweathermap.org/data/2.5/weather?q=London&appid=your_api_key

How API Endpoints Work

Request:
A client (like a web app or mobile app) sends an HTTP request to the API endpoint.
Processing:
The API processes the request, using any provided parameters to fetch or modify the data.
Response:
The API sends an HTTP response back to the client, usually in JSON or XML format.

Example Request:

GET https://api.openweathermap.org/data/2.5/weather?q=London&appid=your_api_key

Example Response:

{
  "location": "London",
  "temperature": "15°C",
  "humidity": "72%",
  "description": "Clear sky"
}

Types of API Endpoints

Endpoints vary based on the type of operations they support. The most common types are:

GET Endpoints: Retrieve data from the server.
- Example: /users retrieves a list of users.
POST Endpoints: Send data to the server to create a new resource.
- Example: /users creates a new user.
PUT Endpoints: Update an existing resource.
- Example: /users/123 updates user data for the user with ID 123.
DELETE Endpoints: Remove a resource.
- Example: /users/123 deletes the user with ID 123.

Example: Designing a Simple API Endpoint

Let’s create an API endpoint for a fictional online library.

Base URL: https://api.mylibrary.com
Endpoint Path: /books

Example 1: GET Request
Retrieve a list of books:

GET https://api.mylibrary.com/books

Response:

[
  {"id": 1, "title": "Python Basics", "author": "John Doe"},
  {"id": 2, "title": "Learning APIs", "author": "Jane Smith"}
]

Example 2: POST Request
Add a new book to the library:

POST https://api.mylibrary.com/books
Content-Type: application/json
Body: {
  "title": "New Book Title",
  "author": "Author Name"
}