Examples of Documenting RESTful APIs

Introduction to Documenting RESTful APIs

Documenting RESTful APIs is crucial for developers and users to understand how to interact with your service effectively. Clarity, precision, and comprehensive examples can significantly enhance user experience, ensuring that your API is accessible and easy to use. Below are three practical examples of documenting RESTful APIs that illustrate different approaches and tools.

Example 1: Basic User Authentication API Documentation

Use Case

In this example, we will document a basic user authentication API, which allows users to log in and receive a token for subsequent requests.

### User Login API

- **Endpoint:** `/api/login`
- **Method:** `POST`
- **Description:** Authenticates a user and returns a JSON Web Token (JWT).

#### Request

- **Headers:**
  - `Content-Type: application/json`
- **Body:**
  ```json
  {
    "username": "user123",
    "password": "securePassword"
  }
 

Response

• Status Code: 200 OK

• Body:

  {
    "token": "eyJhbGciOiJIUzI1NiIs..."
  }
  

Error Responses

• 401 Unauthorized: Invalid credentials.
• 400 Bad Request: Missing username or password.

### Notes

- Ensure that the password is hashed before transmission.
- Consider adding rate limiting for authentication attempts to enhance security.

## Example 2: Product Inventory API Documentation with Swagger
### Use Case
This example demonstrates using Swagger (OpenAPI) to document a product inventory API, which allows users to retrieve product details and stock levels.

```yaml
openapi: 3.0.0
info:
  title: Product Inventory API
  description: API for managing product inventory.
  version: 1.0.0
paths:
  /api/products:
    get:
      summary: Retrieve a list of products
      responses:
        '200':
          description: A list of products
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    name:
                      type: string
                    stock:
                      type: integer

Notes

• Swagger UI can generate interactive documentation, allowing users to test the API directly.
• Consider providing examples of typical responses for better understanding.

Example 3: Weather Data API Documentation with Postman

Use Case

In this example, we will document a weather data API using Postman, which provides current weather information for specified locations.

### Current Weather API

- **Endpoint:** `/api/weather/current`
- **Method:** `GET`
- **Description:** Retrieves current weather data for a given city.

#### Request

- **Query Parameters:**
  - `city`: The name of the city to retrieve weather for (e.g., `London`).

#### Example Request

GET /api/weather/current?city=London

#### Response

- **Status Code:** `200 OK`
- **Body:**
  ```json
  {
    "city": "London",
    "temperature": "15°C",
    "condition": "Cloudy"
  }
 

Error Responses

• 404 Not Found: City not found.
• 500 Internal Server Error: An error occurred on the server.
  ```

Notes

• Include a link to a Postman collection for users to import and test the API easily.
• Consider adding a section for rate limits if applicable.