API Documentation Basics: Writing Clear Endpoints and Responses

Previously in this course, we covered testing with Postman to ensure our endpoints behave as expected. While testing verifies functionality, documentation ensures that other developers—or your future self—can actually use your API without reverse-engineering the codebase.

Good API documentation is the bridge between a functional server and a usable product. Without it, your API is a "black box" that remains a mystery to anyone who didn't write the code. In this lesson, we will focus on documenting your API endpoints, parameters, and responses within your README.md file.

Why Documentation Matters

If you've followed our Professional Project Structure guide, your application is modular and clean. However, a developer looking at your routes/ folder still needs to know:

1. What is the URL path?
2. What HTTP method should I use?
3. What data does the server expect?
4. What will the server return?

Treat your README.md as the primary user manual for your API. As we discussed in Project Setup Strategy, a well-structured repository relies on clear communication to guide contributors.

Documenting API Endpoints

A clear endpoint description should include the HTTP method, the path, and a brief description of its purpose. When documenting, use a consistent format for every route.

The Anatomy of an Endpoint Entry

For every route in your API, provide the following structure:

• Method + Path: POST /api/users
• Description: Creates a new user in the database.
• Request Body: A JSON object containing user details.
• Success Response: HTTP 201 Created with the new user object.
• Error Response: HTTP 400 Bad Request if fields are missing.

Worked Example: Documenting a User Route

Imagine you have an endpoint that creates a user. Here is how you should document it in your README.md:

MARKDOWN
### Create User
**URL**: `/api/users`  
**Method**: `POST`  
**Description**: Creates a new user record.

**Request Body**
```json
{
  "username": "string",
  "email": "string"
}

Success Response

• Code: 201
• Content: {"id": "123", "username": "jdoe", "email": "jdoe@example.com"}

Error Response

• Code: 400
• Content: {"error": "Email is required"}

## Best Practices for API Documentation

To ensure your documentation remains useful as your project grows, follow these professional standards:

| Documentation Element | Goal |
| :--- | :--- |
| **Consistency** | Use the same headers (URL, Method, Payload) for every endpoint. |
| **Examples** | Always provide concrete JSON examples for requests and responses. |
| **Versioning** | If you change an endpoint significantly, update the version or note it. |
| **Status Codes** | Explicitly list the status codes (e.g., 200, 201, 404, 500) so the client knows what to expect. |

As you expand your API, you might eventually use tools like Swagger or OpenAPI to automate this, but writing it manually in your `README` first is the best way to understand *what* information is actually necessary for a consumer.

## Practice Exercise: Document Your API
Open your current project's `README.md` file. Find your primary GET route (e.g., `GET /api/resources`) and your primary POST route. Add a "API Reference" section and document both using the format provided in the "Worked Example" section above. Ensure you include the expected request body for the POST request and the format of the JSON returned for both.

## Common Pitfalls
- **Assuming Knowledge**: Don't assume the reader knows the shape of your data. Always include the full JSON object.
- **Outdated Docs**: Documentation that lies is worse than no documentation. Whenever you change a route's logic, update the `README` immediately.
- **Vague Descriptions**: Avoid saying "returns user data." Be specific: "returns a JSON object containing the user's `id`, `username`, and `createdAt` timestamp."

## FAQ
**Q: Should I keep documentation in the code or the README?**
A: Start in the `README.md`. It keeps the documentation visible and accessible to anyone who clones your repo. As you grow, you can move to code-level comments or automated tools.

**Q: Do I need to document every single status code?**
A: Document the "happy path" (200/201) and the most common error states (400, 401, 404). You don't need to list every obscure server error.

## Recap
Documenting your API is a core part of professional development. By consistently defining your endpoints, request parameters, and response objects in your `README.md`, you make your API predictable and easy to use. Remember: your code is only as good as the ability of others to interact with it.

Up next: We will implement server-side validation to ensure the data your API receives matches the documentation you've just written.