# Endpoint Documentation Template

Use this template for each API endpoint. Copy it to a file named after the endpoint, for example:

```text
documentation/endpoints/create-customer.md
documentation/endpoints/product-list.md
```

Do not document only the Python files for endpoint behavior. For this service, the endpoint contract lives mainly in S3 route/auth/endpoint schemas.

## Endpoint

| Field | Value |
| --- | --- |
| Path | `/api/example` |
| Method | `POST` |
| App group | `mconnect` |
| Auth required | Yes/No |
| Auth modes | Basic/JWT/None |
| IP whitelist | Enabled/Disabled |

## S3 Schema Paths

| Schema | Path |
| --- | --- |
| Route schema | `api_wrapper/api/routes.json` |
| Auth schema | `api_wrapper/authentication/authentication_schema.json` |
| Merchant schema | `api_wrapper/merchant/{merchant_id}/{domain}/{merchant_name}.json` |
| Category schema | `api_wrapper/category/{category_id}/{domain}/{category_name}.json` |
| Admin schema | `api_wrapper/{source}/{domain}/category/default/default.json` |

## Purpose

Describe what the endpoint does from the client's point of view.

## Request Headers

| Header | Required | Description |
| --- | --- | --- |
| `Host` | Yes | Used to resolve domain configuration |
| `Authorization` | Depends | Used for JWT routes |
| custom auth header | Depends | Used when auth schema expects it |

## Request Body Or Query Params

For POST, document the JSON body. For GET, document query params because the service converts query params into `request.get_json`.

```json
{}
```

## Validation

Document important validation rules from:

```text
paths.{endpoint}.{method}.requestBody.content
```

Include field names, types, required status, allowed values, and schema-defined validation messages.

## Business Rules

Document rule blocks from:

```text
paths.{endpoint}.{method}.requestBody.rules.data
```

For each rule:

| Condition | True branch | False branch | Result |
| --- | --- | --- | --- |
|  |  |  |  |

## Functions

Document function blocks from:

```text
paths.{endpoint}.{method}.functions
```

Separate:

- `init` functions
- post-validation functions

Include generated state keys and external calls.

## Persistence

Document persistence blocks from:

```text
paths.{endpoint}.{method}.persistence
```

| Table | Operation | Condition | Important fields |
| --- | --- | --- | --- |
|  |  |  |  |

## Responses

Document each response code from:

```text
paths.{endpoint}.{method}.responses
```

| `cf_code` | HTTP status | Return code | Meaning |
| --- | --- | --- | --- |
| `CF200` | 200 |  | Success |
| `CF300` |  |  | Validation/business failure |
| `CF500` | 500 |  | Internal failure |

## Side Effects

List side effects such as:

- database inserts/updates
- S3 uploads
- external API calls
- generated files
- comments inserted
- CloudWatch logs

## Test Cases

Document at least:

- successful request
- auth failure
- validation failure
- main business-rule failure
- persistence failure or external API failure, if applicable