Skip to content

API Specification

An API (Application Programming Interface) is the way different parts of your application, or different applications, communicate with each other. You document which endpoints exist, what data you can request or send, and how other developers or systems can use your API. It’s like a restaurant menu: it shows what is available and how you can order it.

For this product, you describe the API specification of your application, including all endpoints, request/response formats, and authentication.

API Specification

A good API specification contains:

  • Endpoints: All available endpoints with their HTTP methods (GET, POST, PUT, DELETE, etc.)
  • Request formats: What data you need to send and in which format
  • Response formats: What data you get back and in which format
  • Authentication: How you gain access to the API
  • Error handling: Which error messages you can expect

There are various tools and standards you can use to document your API, such as OpenAPI (formerly Swagger), Postman, or plain markdown documentation.

Quality indicators

When assessing this product, the following quality indicators will be considered:

  • The API specification is a self-contained document that starts with an introduction/contextual text and then describes the different endpoints.
  • There is an overview of all available endpoints with their HTTP methods.
  • For each endpoint, the request format is described (which parameters, body, headers, etc.).
  • For each endpoint, the response format is described (which data is returned, status codes, etc.).
  • It is described how authentication works for the API (if applicable).
  • There are example requests and responses that clearly show how the API can be used.
  • It is described how errors are handled and which error codes are possible.
  • There are references to the code in GitLab where the API is implemented.
  • There is a list of sources in the document describing the materials you used to design and implement the API.

Template

To create your own API specification, you can use the following template:

# API Specification

In this section, describe in a few sentences what the API does and what the goal of the API is. This is the main text of your document.

## Authentication

Here you describe how authentication works for the API (if applicable). Explain which methods are used (for example API keys, JWT tokens, OAuth, etc.) and how they are used.

## Endpoints

Here you describe all available endpoints. For each endpoint, specify:
- The URL and HTTP method (GET, POST, PUT, DELETE, etc.)
- A description of what the endpoint does
- Which parameters, body, or headers are needed
- Which response you get back
- Example requests and responses

### Example Endpoint

**GET /api/users/{id}**

Description: Retrieves a specific user based on the ID.

**Request:**
- Path parameter: `id` (integer) - The ID of the user
- Headers: `Authorization: Bearer {token}`

**Response:**
- Status: 200 OK
- Body: JSON object with user data

**Example Request:**
http
GET /api/users/1
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...


**Example Response:**
{
  "id": 1,
  "name": "John Doe",
  "email": "john@example.com"
}

## Error Handling

Here you describe how errors are handled. Explain which error codes are possible and what they mean. Provide examples of error responses.

## Implementation

Here you describe how the API is implemented in your project. Add references to the code in GitLab and use code snippets to describe the implementation.

## Sources

List here the sources you used to design and implement the API. Think of YouTube videos, websites, books, and so on.
Also include sources that helped you write the code.