API Documentation

API documentation is a guide that explains how an API works and how developers can communicate with it.

Developer
    ↓
API Documentation
    ↓
Endpoint
    ↓
Request
    ↓
REST API
    ↓
Response

Good documentation helps developers:

• Understand API endpoints
• Know which HTTP method to use
• Understand required parameters
• Send the correct request body
• Authenticate correctly
• Understand API responses
• Handle errors
• Integrate the API faster

A useful API document can contain:

• API base URL
• Endpoint URL
• HTTP method
• Authentication requirements
• Request headers
• Path parameters
• Query parameters
• Request body
• Response example
• Status codes
• Error responses

The base URL is the common starting point for API endpoints.

https://example.com/api/

For a versioned API:

https://example.com/api/v1/

The documentation should clearly tell developers which base URL to use.

An endpoint represents a specific API resource or operation.

GET
/api/v1/students.php

The documentation should explain what this endpoint does.

Purpose:
Get a list of students.

Always specify the HTTP method.

GET     → Read data
POST    → Create data
PUT     → Replace data
PATCH   → Partially update data
DELETE  → Delete data

This prevents developers from guessing how an endpoint should be called.

GET /api/v1/students.php

Purpose:

Returns all students.

Example response:

{
    "success": true,
    "data": [
        {
            "id": 1,
            "name": "Rahul"
        }
    ]
}

POST /api/v1/students.php

Purpose:

Create a new student.

Request body:

{
    "name": "Rahul",
    "course": "React Native"
}

PUT /api/v1/students.php?id=10

Explain which fields are required and how the complete resource should be updated.

{
    "name": "Rahul Kumar",
    "course": "React Native"
}

DELETE /api/v1/students.php?id=10

Purpose:

Deletes the student with ID 10.

Document the required ID and possible response codes.

Query parameters are values supplied after ? in the URL.

GET
/api/v1/students.php?search=rahul

Documentation should explain:

• Parameter name
• Data type
• Required or optional
• Purpose
• Example value

A path parameter is part of the URL path.

GET
/api/v1/students/10

Here 10 represents the student ID.

Documentation should clearly explain what the parameter represents.

Headers provide additional information about a request.

Content-Type: application/json

Authorization:
Bearer YOUR_JWT_TOKEN

Document which headers are required and when they should be included.

If an API requires authentication, explain the authentication process.

1. Login
2. Receive JWT
3. Store token securely
4. Send token with protected requests

Example:

Authorization:
Bearer YOUR_JWT_TOKEN

For POST, PUT, or PATCH requests, document the expected JSON body.

{
    "name": "Rahul",
    "email": "rahul@example.com",
    "course": "React Native"
}

Explain the purpose and data type of each field.

This allows the mobile developer to prepare the request correctly.

Explain the structure of a successful API response.

{
    "success": true,
    "message": "Student created successfully",
    "data": {
        "id": 25,
        "name": "Rahul"
    }
}

Developers should know which fields are returned and what they mean.

Documentation should explain possible errors.

{
    "success": false,
    "message": "Student not found"
}

Also document the HTTP status code associated with the error.

For a search API, document the parameter and example request.

GET
/api/v1/students.php?search=rahul

Explain whether the search works on name, email, student ID, course, or other fields.

GET
/api/v1/students.php?page=2&limit=10

Document what page and limit mean.

{
    "success": true,
    "data": [],
    "pagination": {
        "page": 2,
        "limit": 10,
        "total": 50,
        "total_pages": 5
    }
}

If your API supports sorting and filtering, document the supported parameters.

GET
/api/v1/students.php
?course=React
&sort=name
&order=asc

Clearly list which filter and sort values are supported.

A React Native developer should be able to understand the endpoint from the documentation and call it using Fetch or Axios.

const response =
    await fetch(
        "https://example.com/api/v1/students.php"
    );

const result =
    await response.json();

console.log(result);

The documentation should make clear what the developer should expect in result.

OpenAPI is a standard format for describing REST APIs. Swagger tools can be used to display and work with OpenAPI documentation.

OpenAPI Specification
        ↓
API Description
        ↓
Swagger UI
        ↓
Interactive Documentation

This can be useful when an API contains many endpoints.

Postman collections can organize API requests and provide examples for developers.

Collection
 ├── Authentication
 ├── Students
 ├── Users
 ├── Search
 └── File Upload

A collection can make it easier to test and demonstrate API endpoints.

Documentation should be updated whenever the API changes.

API Change
    ↓
Update Code
    ↓
Update Documentation
    ↓
Test Endpoint
    ↓
Publish Updated Documentation

Outdated documentation can be almost as problematic as missing documentation.

• Base URL
• API version
• Endpoint
• HTTP method
• Authentication
• Request headers
• Parameters
• Request body
• Response example
• Error example
• Status codes
• Pagination and filtering rules

GET /api/v1/students.php

Purpose:
Get students.

Authentication:
Bearer JWT required.

Query Parameters:
search - optional string
page   - optional integer
limit  - optional integer

Response:

{
    "success": true,
    "data": [
        {
            "id": 1,
            "name": "Rahul"
        }
    ]
}

Possible Status Codes:

200 - Success
401 - Unauthorized
422 - Validation Error
500 - Server Error

A developer can use this information to integrate the endpoint without opening the PHP source code.

Good API documentation explains the complete communication contract between the client and server. It should describe endpoints, methods, authentication, parameters, request bodies, responses, errors, and examples.

Documentation
      ↓
Endpoint
      ↓
Request
      ↓
Authentication
      ↓
Response
      ↓
Error Handling
      ↓
React Native Integration

Well-written documentation makes your REST API easier to maintain, test, integrate, and use by other developers.