Visit djangoplay.org ↗
templates / API template
DocsTemplatesAPI template

API template

Document every endpoint the same way. Use placeholders for real hosts, tokens and ids. Delete every template comment before committing.

1 min readTemplates
markdown
---
title: {{title}}
description: {{description}}
type: api
since: {{since}}
---

<!-- template: document every endpoint the same way. Use placeholders for real hosts, tokens and ids. Delete every template comment before committing. -->

## Overview

What the API is for and who calls it.

## Authentication

How a caller proves who they are, and which header or token to send.

## Base URL

```text
https://<host>/api/v1/
```

## Endpoints

### List resources

`GET /api/v1/<resource>/`

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `page` | query | integer | Page number. |

Response `200`:

```json
{ "results": [] }
```

### Create a resource

`POST /api/v1/<resource>/`

```json
{ "field": "value" }
```

## Errors

| Status | Code | Meaning |
| --- | --- | --- |
| `400` | `validation_error` | The request body is invalid. |
| `401` | `unauthenticated` | Missing or invalid credentials. |
| `404` | `not_found` | The resource does not exist. |