Welcome to part 3 of our API development series! In this article, we will cover how to read typical REST API documentation.
REST API documentation typically provides information about the available resources, endpoints, methods, and parameters of an API. It is important to read and understand this documentation in order to effectively use and integrate with an API.
Here are some common elements that you may find in REST API documentation:
- Endpoints: Endpoints are the URLs that you use to access specific resources or data within an API. API documentation should provide a list of all available endpoints, along with a description of what each endpoint does.
- Methods: HTTP methods (also known as verbs) are used to indicate the action that you want to perform on a specific resource or endpoint. The most common HTTP methods are GET (to retrieve data), POST (to create new data), PUT (to update existing data), and DELETE (to delete data). API documentation should indicate which methods are supported by each endpoint.
- Parameters: Parameters are used to modify or filter the data returned by an API endpoint. API documentation should provide a list of all available parameters, along with a description of what each parameter does and how to use it.
- Responses: Responses are the data that the API returns in response to a request. API documentation should provide a list of all possible response codes and messages, along with a description of what each code means.
- Authentication: API documentation should also provide information on how to authenticate with the API, including any required keys, tokens, or credentials.
Let’s take a look at an example of REST API documentation and how to read it:
Endpoint: /users
Methods:GET, POST
Parameters:
– id: optional, integer
– name: optional, string
– email: optional, string
Responses:
– 200 OK: returns an array of user objects
– 404 NotFound: returns an error message if the specified user is not found
Authentication:Header Key Authentication, requires an API key
In this example, we see that the API endpoint is located at (root URL)/users (so in our example, https://dummyapi.com/users) and supports the GET and POST methods. We can also see that there are three optional parameters: id, name, and email, which can be used to filter the returned user objects. The API returns an array of user objects in a 200 OK response, and returns an error message in a 404 Not Found response if the specified user is not found. Finally, we can see that authentication is required and is accomplished through Header Key Authentication, using an API key.
API documentation references
Here are links to the API documentation references to a few of the tools we use.
Connectwise Developer (Manage, Automate, Control – requires registration)
IT Glue
Microsoft Graph
