How to Document APIs – CHAT-GPT

Can CHAT-GPT write technical documentation? Like many tech writers, I’ve been looking at ways to use CHAT-GPT, Huggingface, and Google Bard to help with tech doc tasks.

Over the coming weeks, I’ll be looking at different ways to leverage this tool to write, review, generate, and automate different aspects of technical documentation.

How to Document APIs – CHAT-GPT

I asked CHAT-GPT to provide guidelines on how to document APIs. Here’s what it came back with.

Prompt: Provide me with guidelines to documents APIs. Provide details for each item in the list.

CHAT-GPT response: Documenting APIs is an essential part of ensuring that developers can understand and use your API effectively. Good API documentation provides clear instructions, examples, and reference information. Here are some steps to help you document APIs effectively:

1. Introduction: In this section, provide a brief overview of your API, its purpose, and its target audience. Explain the problem it solves and the benefits it offers to developers. For example: “Welcome to the XYZ API documentation. Our API provides real-time weather data for locations worldwide. With our API, developers can access current weather conditions, forecasts, and historical data to enhance their applications with accurate weather information.”
2. Getting Started: Include step-by-step instructions on how to get started with your API. This should cover obtaining API credentials, installing any necessary libraries or SDKs, and authentication steps. For example:
   • To start using the XYZ API, follow these steps:
     1. Sign up on our website to obtain your API key.
     2. Install our Python SDK using pip: pip install xyz-api.
     3. Import the SDK into your project and initialize it with your API key.
     4. Make your first API request to retrieve weather data for a specific location.
3. Endpoints and Resources: Document each endpoint or resource provided by your API. Include the URL, HTTP methods, and a brief description of each endpoint. For example:
   • Endpoint: /weather
     • Description: Retrieves weather data for a specific location.
     • HTTP Method: GET
     • Parameters: location (required) – The name or ID of the location.
     • Example Request: GET /weather?location=New%20York
     • Example Response: { "location": "New York", "temperature": 25, "humidity": 70 }
4. Request and Response Formats: Specify the expected format for requests and responses, such as JSON or XML. Provide examples of valid request payloads and corresponding response structures. For example:
   • Request (JSON):{ "location": "New York" }
   • Response (JSON):{ "location": "New York", "temperature": 25, "humidity": 70 }
5. Authentication and Authorization: Explain the authentication methods and how developers can authenticate their requests to the API. Provide code examples for each authentication method. For example:
   • API Key Authentication:
     • To authenticate your requests, include the X-API-Key header with your API key:GET /weather?location=New%20York X-API-Key: your-api-key
6. Error Handling: Document the possible error scenarios and how they are communicated to developers. Provide a list of common error codes, their meanings, and example error responses. For example:
   • Error Response: HTTP/1.1 <span class="hljs-number">404</span> Not Found <span class="hljs-attribute">Content-Type</span>: application/json <span class="json">{ <span class="hljs-attr">"error"</span>: <span class="hljs-string">"Location not found"</span> }</span>
7. Rate Limiting: If your API has rate limits, clearly state the limits and how they are enforced. Include headers or response fields indicating the current rate limit status. For example:
   • Rate Limit Headers:X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 50 X-RateLimit-Reset: 1623355200
8. Examples and Use Cases: Include practical examples that demonstrate how to use your API in real-world scenarios. Show common use cases and provide code snippets in different programming languages. For example:
   • Example: Retrieving weather data using ChatGPT JavaScript Fetch API:fetch('https://api.xyz.com/weather?location=New%20York', { headers: { 'X-API-Key': 'your-api-key' } }) .then(response => response.json()) .then(data => { console.log(data); });
9. Code Reference: Provide a detailed reference section that lists all available endpoints, request parameters, response objects, and their properties. Organize the reference section in a logical manner. For example:
   • Endpoint: /weather
     • Description: Retrieves weather data for a specific location.
     • HTTP Method: GET
     • Parameters:
       • location (required, string): The name or ID of the location.
     • Response:
       • location (string): The name of the location.
       • temperature (number): The current temperature in degrees Celsius.
       • humidity (number): The current humidity percentage.
10. Tutorials and Guides: Supplement the reference documentation with tutorials and guides. For example, you can create a step-by-step guide on integrating your API with a popular framework or provide a tutorial on how to build a specific feature using your API.
11. Versioning: Explain how to specify the API version in requests and how changes are managed. Document any deprecated endpoints or features and provide guidance on migration paths. For example:
    • To specify the API version, include the version number in the URL path:GET /v1/weather?location=New%20York
12. Changelog: Maintain a changelog that outlines the version history of your API. Include release notes for each version, highlighting new features, bug fixes, and breaking changes. For example:
    • Version 1.1.0 (Released: June 1, 2023):
      • Added support for historical weather data.
      • Deprecated the /forecast endpoint. Use /weather instead.
13. Support and Contact Information: Provide information on how developers can get support or report issues related to your API. Include contact details or links to support forums or issue trackers. For example:
    • If you have any questions or encounter any issues, please email us at [email protected] or visit our support forum at https://forum.xyz.com.
14. Interactive Documentation: Consider providing interactive documentation using tools like Swagger, OpenAPI, or Postman. For example, you can generate an interactive API documentation page with code snippets and the ability to make requests directly from the documentation.

Remember, the goal is to provide comprehensive and user-friendly documentation that enables developers to integrate and use your API with ease.

How to Document APIs – Google Bard

Next, I asked the same question to Google Bard. As you can see, it provides more high level details but doesn’t (yet) provide the same level of detail. I prompted it for more details but the response was more or less the same.

Google Bard response:

API documentation is a critical part of any API development project. It helps developers understand how to use your API, which can lead to increased adoption and usage. There are many different ways to document APIs, but some of the most common methods include:

• Written documentation: This is the most traditional form of API documentation. It typically includes a high-level overview of the API, as well as detailed descriptions of each endpoint, parameter, and response.
• Interactive documentation: This type of documentation uses a web-based interface to allow developers to explore the API in a more interactive way. This can be done using tools like Swagger UI or RAML Editor.
• Code samples: Code samples are a great way to show developers how to use your API in real code. They can be included in written documentation or in a separate repository.

No matter which method you choose, it’s important to make sure your API documentation is complete, accurate, and easy to use. This will help developers get up and running with your API quickly and easily.

Here are some additional tips for writing good API documentation:

• Start with the basics: Your documentation should start with a high-level overview of the API, including its purpose, target audience, and supported features.
• Be specific: When describing each endpoint, parameter, and response, be as specific as possible. This will help developers avoid making mistakes.
• Use examples: Code samples are a great way to show developers how to use your API in real code.
• Keep it up-to-date: As you make changes to your API, be sure to update your documentation accordingly.

By following these tips, you can create API documentation that is clear, concise, and helpful. This will make it easier for developers to use your API, which can lead to increased adoption and usage.

Here are some tools that can help you document your APIs:

• Swagger UI: Swagger UI is a popular tool for generating interactive API documentation. It can be used to generate documentation for APIs that are defined using the OpenAPI Specification (OAS).
• RAML Editor: RAML Editor is a tool for generating API documentation from RAML definitions. RAML is an alternative to the OAS that is designed to be more human-readable.
• Postman: Postman is a popular tool for testing APIs. It can also be used to generate documentation for APIs.

These are just a few of the many tools that can help you document your APIs. The best tool for you will depend on your specific needs and preferences.

Summary

While CHAT-GPT isn’t perfect, it did manage to provide a set of generic guidelines that met the brief. For now, it provides more detail than Google Bard. It seems, and probably is, pulling from a larger data set and/or can provide more contextual information.

Next week, I’ll drill down into other tech doc tasks with CHAT-GPT as my virtual co-author.

Image credit: ilgmyzin