Recommended API Document Directory Structure

This article is generated by Google Gemini.

Here is a recommended directory structure and a writing standard for your API documentation.

1. Recommended Directory Structure

A logical structure helps developers quickly navigate and find exactly what they need, whether it’s a quick reference or a full tutorial.

/docs
|-- /reference                  // Core API Reference (by Resource)
|   |-- /authentication         // Auth/Token Endpoints
|   |   |-- POST_login.md
|   |   |-- POST_register.md
|   |-- /users                  // User Management Endpoints
|   |   |-- GET_users.md        // Recommended: Named by HTTP Method and Resource
|   |   |-- GET_user_id.md
|   |   |-- PATCH_user_id.md
|   |-- /products               // Product Catalog Endpoints
|   |   |-- ...
|   |-- SUMMARY.md              // Navigation file for the reference section
|
|-- /guides                     // Tutorials and Explanations
|   |-- getting-started.md      // Quickstart guide
|   |-- auth-flow.md            // Detailed OAuth/Token explanation
|   |-- pagination.md           // How to handle large lists
|   |-- error-codes.md          // Comprehensive list of error codes
|
|-- README.md                   // Main documentation entry point/Overview
|-- CHANGELOG.md                // Record of API changes and versioning

Structure Explanation:

1. /reference (API Reference): This is where you put the specifications for every single endpoint.
   • Group by Resource: Organize files into folders based on the resource (e.g., all user endpoints go in /users).
   • File Naming: Use the pattern [HTTP_METHOD]_[resource_name].md (e.g., GET_user_id.md) for clarity at a glance.
2. /guides (Guides/Tutorials): This section provides context and explains workflows, not individual endpoints. This is crucial for onboarding new users.
3. README.md: The landing page for your documentation. It should include a high-level overview, API base URL, version information, and links to the Getting Started guide.

2. Markdown Writing Standard (Single Endpoint)

Consistency is key. Use a standardized template for every single API file (e.g., GET_user_id.md) to make them predictable and easy to scan.

A. Endpoint Header and Overview

Use the highest level heading (#) for the endpoint itself.

# GET /users/{id} - Retrieve User Details

**Description:** Use this endpoint to fetch the detailed profile information for a single user by their unique ID.
**Authorization:** Requires a valid **Access Token** with the `read:user` scope.
**Status:** Stable / Beta / Deprecated

B. Request Section

Use Markdown Tables for parameters to structure the information clearly.

## 1. Request

### URL
`GET https://api.example.com/v1/users/{id}`

### Path Parameters
| Name | Type | Required | Description | Example |
| :--- | :--- | :--- | :--- | :--- |
| **id** | `integer` | Yes | The unique identifier for the user. | `54321` |

### Query Parameters
| Name | Type | Required | Description | Default |
| :--- | :--- | :--- | :--- | :--- |
| `fields` | `string` | No | A comma-separated list of fields to return. If omitted, all fields are returned. | `null` |

### Request Headers
| Name | Required | Description | Example |
| :--- | :--- | :--- | :--- |
| `Authorization` | Yes | Bearer token for authentication. Format: `Bearer {token}`. | `Bearer xyz123abc` |
| `Content-Type` | No | Request body type. Usually `application/json` for POST/PUT/PATCH. | `application/json` |

C. Response Section

Use Fenced Code Blocks (```json or ```bash) to display code and payloads.

## 2. Response

### Success Response (Status: 200 OK)

**Description:** The user details were successfully retrieved.

```json
{
  "code": 200,
  "status": "success",
  "data": {
    "id": 54321,
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane@example.com",
    "createdAt": "2023-10-01T10:30:00Z"
  }
}

Response Fields

Error Responses

See also: Full Error Code Reference

Example cURL Call

curl -X GET \
  -H "Authorization: Bearer xyz123abc" \
  "[https://api.example.com/v1/users/54321](https://api.example.com/v1/users/54321)"

Summary of Best Practices:

1. Use Tables for Structure: Parameters and Response Fields should always be in Markdown tables for easy scanning.
2. Use Fenced Code Blocks: Use ```json for payloads and ```bash for cURL examples.
3. Link Everything: Use relative links (e.g., [Full Error Code Reference](/guides/error-codes.md)) to connect related documents.
4. Be Explicit: Clearly state the required fields, data types, and default values.