What is an API endpoint?
Greetings, and welcome to the first of a miniseries on the blog covering some fundamental concepts in APIs, or Application Programming Interfaces.
We’re taking a different approach with these posts; instead of providing a long and detailed explanation of APIs and the most important things to know in a single post, we’ll be breaking them down and making each entry short and punchy.
That should help you find the answers you’re looking for quicker, and perhaps even encourage you to read the full post rather than give it a quick skim. Here’s hoping!
So, without further ado, here’s a primer on API endpoints. Check back in the coming weeks for posts covering API keys and API calls.
API endpoints defined
An API endpoint is where an API receives requests. For most services, these endpoints are URLs, just like the ones you use to navigate to a website.
How API endpoints work
Let's take a closer look at how API endpoints work. Here's an example of an endpoint URL:
https://api.github.com/repos/torvalds/linux
This endpoint belongs to the GitHub REST API and returns information about a repository as a JSON object.
API endpoints have a base path that’s usually a dedicated subdomain, like cdn.contentful.com, graphql.contentful.com, or https://collectionapi.metmuseum.org/. They can also be presented as paths within the main site, like https://mandrillapp.com/api but it’s rarer.
Then, to complete the endpoint, you add a suffix to that base URL that specifies what you want. In the example above, that’s the `repos` in api.github.com/repos.
From an API design perspective, this lets developers create and maintain logical groupings.
Some APIs have a hierarchical structure, using path values to create a parent/child relationship.
Examples of API endpoints with Contentful
Let’s explain this using Contentful’s Content Delivery API as an example of a hierarchical API. Its base URL is https://cdn.contentful.com.
So, to access the resources in the space ID nxk0n1u8oy59, you would use the following path: https://cdn.contentful.com/spaces/nxk0n1u8oy59/
The Content Delivery API documentation shows you the other endpoints available.
In the documentation’s website, clicking the Content Model endpoint under Content Types shows the following details, including the request type and query parameters.
In this instance, this endpoint requires an API Key for authentication, and only allows GET requests, which is the default for requesting data. Other endpoints let you use other HTTP methods to perform various functions, such as POST, PUT, PATCH, DELETE, etc.
Additionally, note that you need to secure the API request above by supplying the API key as an access_token parameter, ensuring the system can identify who’s making the call.
For internal development, APIs can be accessed from a local server using localhost. Sometimes you can also use a direct internal IP address ( e.g., 10.0.1.1) and not a subdomain to access an API.
Wrapping up
In summary, an API endpoint is a specific location within an API that accepts requests and sends back responses. It's a way for different systems and applications to communicate with each other, by sending and receiving information and instructions via the endpoint.
It allows developers to access data and functionality from other systems, and to create new apps that can easily access and use data and functionality from other systems, without having to build everything from scratch.
In our next posts, we’ll be talking about API keys and API calls. See you soon.
