How to Document Your API?

Your API needs documentation.

Photo by Alvaro Reyes on Unsplash

API documentation guides developers, outlining the available endpoints, request and response formats, authentication methods, parameters, and other details required to use the API successfully.

It serves as a comprehensive reference guide, providing instructions, examples, and specifications to help developers integrate their applications with the API seamlessly.

Location API Documentation

The locations API provides endpoints for retrieving information about different locations of users.

Base URL

http://127.0.0.1:8888/api/v1.0/

Above is the base URL for any GET, POST, DELETE, PUT etc. Mapping.

Authentication

API requests require authentication using an API key. Include the API key in the headers of your requests:

Authorization: Bearer {API_KEY}

Endpoints

Get UserLocation Details: You can retrieve the details of a specific location or fetch all the Locations.

GET api/v1.0/locations

If you have noticed, I am not giving any query or path parameter. I am fetching all the locations stored in the database. So, I have used locations

• Status Code: 200 (OK)
• Content-Type: application/json

[
   
    {
        "locationId": 1,
        "locationName": "cityA",
        "latitude": 2322.122,
        "longitude": 224.122
    },
    {
        "locationId": 2,
        "locationName": "cityB",
        "latitude": 232.122,
        "longitude": 24.122
    },
    {
        "locationId": 3,
        "locationName": "cityC",
        "latitude": 22.122,
        "longitude": 214.122
    }
]

You can see the response above, an object in JSON format.

Error Handling

In case of an error, the API will return an appropriate error response. The following error codes may be encountered:

• 400 (Bad Request): Invalid or missing request parameters.
• 401 (Unauthorized): Invalid or missing API key.
• 404 (Not Found): The requested locations do not exist.
• 500 (Internal Server Error): An unexpected error occurred on the server.

@GetMapping("/locations")
public ResponseEntity<List<UserLocation>>  findAll()
{
   List<UserLocation> userLocation = userService.findAll();
   // Return response entity
   if (userLocation != null && !userLocation.isEmpty()) {
      logger.info("print logs" +userLocation);
      return ResponseEntity.ok(userLocation);
   } else {
      logger.info("not print logs");
      return ResponseEntity.notFound().build();
   }
}

So, this is my GET Mapping; If the user location object is empty. It will return the error code, and else the block will get executed.

ResponseEntity.notFound().build();

404 (Not Found): The requested user location does not exist.

Rate Limiting

The locations Details API enforces rate limiting to ensure proper usage. The following rate limits apply:

• Maximum of 100 requests per minute per API key.

When the rate limit is exceeded, the API will respond with the following error:

HTTP/1.1 429 Too Many Requests 
Content-Type: application/json
{ 
“error”: “Rate limit exceeded. Please wait and try again.” 
}

SDKs and Libraries

We provide SDKs and libraries in various programming languages to simplify the integration of the locations API into your application. Visit out official documentation website.

Versioning

The locations API is currently on version 1. We follow semantic versioning for API changes. If backward-incompatible changes are introduced, a new version will be created.

Support

If you have any questions or issues regarding the locations API, please email your query to the support team.

Conclusion

Well-documented APIs help developers understand how to leverage the API’s features, reduce development time, and encourage integration with other systems and applications. Effective API documentation should be clear, concise, and easy to navigate.

When developers find the documentation intuitive, organized, and easy to navigate, it positively impacts their work, performance, and overall thought process.

Also, if your API is well documented, integration with other systems and applications becomes effortless. It enables effective collaboration, facilitates troubleshooting, and reduces the dependency on others.

Takeaways:

Takeaways sections I include for those who don’t have time to read the full blog post;

In the API documentation, you have to take care of the following points:

1. Give an Introduction — An overview of the API, its purpose, and its functionality.
2. Step-by-step instructions on how to access and authenticate with the API. This section covers prerequisites, API keys, authentication tokens, and any necessary setup or configuration.
3. Detailed descriptions of each API endpoint, including the HTTP method (GET, POST, PUT, DELETE), the endpoint URL, and the purpose of the endpoint. This section also explains the request/response structure, available parameters, and any required or optional headers.
4. Definitions and explanations of the data structures and objects used in requests and responses.
5. Information on how errors and exceptions are handled by the API, including error codes, error messages, and potential troubleshooting steps.
6. Practical examples and use cases to perform the task
7. Guidelines and restrictions related to API usage, including rate limits, throttling, and any usage policies or terms of service that developers must adhere to.
8. Documentation should include Software Development Kits (SDKs) or libraries available for popular programming languages.
9. If the API has multiple versions, the documentation should clearly indicate the versioning scheme and how to specify the desired version in API requests.
10. Include Links to related resources, such as API reference guides, tutorials, FAQs, support channels, and community forums.

“Introduction
Authentication
Endpoints Description
Data structure information used in request and response
Error Handling
Practical Examples
Guidelines for Rate Limiting
SDKs or Libraries
Versioning
Support”

Thank You!