Skip to main content
Practice

4

deck​

What is API Documentation?​

API documentation is technical documentation that helps developers communicate with a specific application.

It typically includes information such as:

  • The functions provided by the API
  • The data required to make a request
  • The expected response data
  • Error handling procedures

Common English Terms Used in API Documentation​

TermMeaning
endpointThe URL path where the API receives requests
requestA request sent by the client to the server
responseA response sent by the server to the client
parameterValues included in the request (e.g., query, path, body)
status codeA numerical code that indicates the status of the response (e.g., 200, 404)
authenticationThe method of verifying identity (e.g., token, OAuth)
error messageA message sent when an error occurs
rate limitRestrictions on API calls (e.g., requests per second)
paginationMethod of dividing data (e.g., pagination)
versioningMethod of managing API versions (e.g., v1, v2)
documentationThe act of documenting the API (e.g., Swagger, OpenAPI)

These terms are typically used as nouns to describe various elements of API requests and responses.

===

Example of API Documentation (Based on REST)​

POST /api/users

Request Body:
{
  "name": "Alice",
  "email": "alice@example.com"
}

Response:
Status: 201 Created
{
  "id": "123",
  "name": "Alice",
  "email": "alice@example.com"
}

It is usually structured in the following way:

  • HTTP method and URL
  • Request format (headers, body, etc.)
  • Response format (status code, data)

===

Tips for Writing API Documentation​

  • Specify the request method (GET, POST, etc.).
  • Provide the type and example value for each field.
  • Differentiate between required and optional parameters.
  • Include explanations for error responses.

Example:

GET /api/users/:id

Path Parameter:
- id (string): Unique ID of the user

Response:
- 200 OK: Returns user information
- 404 Not Found: User not found

Want to learn more?

Join CodeFriends Plus membership or enroll in a course to start your journey.