API and how to design an endpoint
Application programming interface (API) is an interface which is used to exchange data between computers without human interference. API describes the ways and rules which can be used for interactions between computers, such as set of classes, structures, methods, functions etc…
For example, many web apps nowadays allow users to log in with their existing, for example, Facebook accounts instead of registering new usernames and passwords. This means that a third-party site sends an API request to Facebook login API services to check if the person is already logged in with his/her Facebook account and if not, this third-party app will redirect the user to a Facebook log-in page in order to let Facebook verify the info about the person and share some public data about him.
The API request is also called URL request as the client is linking to a specific URL on the server which provides an access point. The data which is sent back to the client is called a response or resource.
Usually API documentation describes all parts of the API such as:
endpoints, which indicate how to access the resource
methods, which indicates allowed methods (CRUD: POST (create), GET (read), PUT (update) and DELETE (delete))
headers, which are sets of colon-separated name-value pairs with meta-data associated with the API request and response such as: message encoding, name and version of the browser, address from the client came from (referrer), etc.
data (or body), which is usually a JSON file with the requested information.
So, what needs to be considered when designing an API endpoint?
Here is an example of the endpoint:
Structure of the endpoint
The endpoint shows the entire path to the resource. However, in the documentation, usually the resource URL is spitted into more specific parts:
the base path refers to the common path for the API.
In the above example, the base path for youtube API is https:// www.googleapis.com/youtube/v3;
the route to the end part of the endpoint: /search
A search result set will include matching video, channel, and playlist resources, unless the query is configured to include only a specific type of resource.
The path is followed by query string parameters for this point:
?part=snippet&q=cats&publishedAfter=2020-04-28T00:31:57Z
Query parameters
An endpoint usually includes query parameters that define more detailed information about the representation of the resource the client requested. For example, in the above endpoint in the query parameter we specify the date frame of the requested objects asking for videos published after April 28, 2020. We’ll get 5 items as a response as this is a default value. According to the documentation of the youtube API, if we want a different number of resource instances, the maxResults parameter can specify this number which should be between 0 and 50.
Some of the parameters are required parameters, that must be identified in the documentation. In the above request: The part parameter is required and specifies a list of one or more search resource properties that the response should include. Failure to include a required parameter in your request will result in 400 error.
Configuration
Some APIs are public and need less configuration. Others can require authorization credentials etc. For example, to be able to use the YouTube Data API you must get an API key and include it in the API request.
The API request can be sent with any programming language.