Endpoint documentation structure in Rest API

Introduction

Endpoint documentation helps people understand how to use a web service. It explains what each URL does and how to talk to it.

When you build a web service that others will use.

When you want to explain how to send data to your API.

When you want to show what data your API sends back.

When you want to help developers avoid mistakes using your API.

When you want to keep your API easy to maintain and update.

Syntax

Rest API

Endpoint: /resource
Method: GET | POST | PUT | DELETE
Description: What this endpoint does
Request Parameters:
  - name (type): description
Request Body:
  {
    "field": "type"
  }
Response:
  Status Code: description
  Body:
  {
    "field": "type"
  }

Use clear names for endpoints and methods.

Include examples of requests and responses if possible.

Examples

This example shows how to get users with a page number.

Rest API

Endpoint: /users
Method: GET
Description: Get a list of users
Request Parameters:
  - page (int): page number
Response:
  Status Code: 200 OK
  Body:
  [
    {"id": 1, "name": "Alice"},
    {"id": 2, "name": "Bob"}
  ]

This example shows how to add a new user by sending their name and email.

Rest API

Endpoint: /users
Method: POST
Description: Create a new user
Request Body:
  {
    "name": "string",
    "email": "string"
  }
Response:
  Status Code: 201 Created
  Body:
  {
    "id": 3,
    "name": "string",
    "email": "string"
  }

Sample Program

This shows how to document an endpoint that returns books. It explains the URL, method, parameters, and response.

Rest API

/* Example of endpoint documentation for a simple API */

Endpoint: /books
Method: GET
Description: Retrieve a list of books
Request Parameters:
  - author (string, optional): filter books by author name
Response:
  Status Code: 200 OK
  Body:
  [
    {"id": 101, "title": "Learn REST", "author": "Jane"},
    {"id": 102, "title": "API Basics", "author": "John"}
  ]

Important Notes

Always keep your documentation up to date with your API changes.

Use simple language so everyone can understand.

Include error codes and messages to help users fix problems.

Summary

Endpoint documentation explains how to use each API URL.

It includes method, parameters, request and response details.

Good documentation makes APIs easier and safer to use.