Skip to content
DocX

API Documentation Guide

API Documentation Template

When documenting an API, use the following structure:

1. API Name and Overview

Provide a clear, descriptive name for the API and a concise overview of its purpose.

Example:

## User Authentication API


This API handles user authentication including login, registration, password reset, and token validation.

2. Technical Implementation

Explain the underlying implementation, including service details and deployment information.

Example:

### Implementation Details


- **Service Name:** authentication-api
- **Service Link:** [GCP Console Link](https://console.cloud.google.com/kubernetes/deployment/us-central1/servers-us-central-production-cluster/default/authentication-api)
- **Jenkins Pipeline:** [Jenkins Link](https://jenkins.msgsndr.com/job/staging/job/auth/job/auth-backend-server)
- **Repository:** [GitHub Repo Link](https://github.com/organization/auth-service)

3. Endpoint Documentation

Document each endpoint using this structure:

### [METHOD] [endpoint-path]


#### Description
Brief description of what the endpoint does.


#### Request
- **Parameters:** List all query parameters or path parameters
- **Headers:** Required headers (authentication, content-type, etc.)
- **Body:** JSON schema of the request body (if applicable)


#### Response
- **Status Codes:** List all possible status codes and their meanings
- **Response Body:** JSON schema of the response with field descriptions


#### Example Request
```json
{
  "field1": "value1",
  "field2": "value2"
}

Example Response

{
  "id": "1234",
  "status": "success",
  "data": {
    "property": "value"
  }
}
### 4. Security and Access Control


Document authentication and authorization requirements.


**Example:**
```md
### Security


#### Guards
- `jwtAuthGuard` - Verifies a valid JWT token is provided
- `roleBasedGuard` - Ensures user has required permissions


#### Validators
- `inputValidator` - Validates request body follows required schema

5. Dependencies and Impact

Document service dependencies and potential impact areas.

Example:

### Dependencies


If this API experiences issues, check these dependent services:
- [user-profile-service](https://console.example.com/service/user-profile)
- [notification-service](https://console.example.com/service/notifications)


### Usage Areas
- User Management Portal
- Mobile App Authentication
- Third-party Integrations

6. Change Log

Keep a dated record of significant changes with links to relevant resources.

Example:

## Change Log


### 2023-12-15
- **PR:** [#1234](https://github.com/org/repo/pull/1234)
- **Task:** [TASK-567](https://clickup.com/t/123abc)
- **Changes:**
  - Added email verification endpoint
  - Updated token validation logic

Best Practices

  1. Be Specific: Avoid vague descriptions, placeholders, or templated text
  2. Include Examples: Provide complete, realistic examples for requests and responses
  3. Document Edge Cases: Note rate limits, error scenarios, and special conditions
  4. Keep Updated: Update documentation when API changes occur
  5. Use Markdown Formatting: Properly format code blocks, tables, and sections

Example

Get Funnel by Id

The API which allows us to get an entry from funnels collection in MongoDB by it’s Id.

Explain API logic step by step if the API makes internal calls to other services or how does the high level logic work for this API

GitHub

Service

<Service Link (Kubernetes or any other GCP link)>

Example

Funnels API (funnels-api)

Service Link https://console.cloud.google.com/kubernetes/deployment/us-central1/servers-us-central-production-cluster/default/funnels-api/overview?inv=1&invt=AbkhYA&project=highlevel-backend

Jenkins Pipeline: https://jenkins.msgsndr.com/job/staging/job/leadgen/job/leadgen-backend-server

Example

GET funnels/funnel/getById

Request (Query/Body/Params)

Response

Guards

  • Guard 1
  • Guard 2
  • .
  • .
  • Guard n

Example (if guarded)

  • rolebasedAccessGuard (link doc)
  • funnelGuard (link doc)

Example (if open)

This API is open and does not have any guards but validators might be present

Validators

  • Validator 1
  • Validator 2
  • .
  • .
  • Validator n

Example (if not applicable remove this section)

  • funnelValidator (link doc)
  • locationValidator (link doc)

Usage

  • Team 1
  • Team 2
  • .
  • .
  • Team n

Example

  • Funnels
  • Workflows

Dependencies

If this API goes down, these are the other areas which needs to be checked, these can be internal api calls which the API logic uses to get data from other services

  • Service 1
  • Service 2
  • .
  • .
  • Service n

Example

Change Log