API Reference template
Use this template to create pages in the API Reference section of the Lerian documentation. It ensures consistency, clarity, and a great developer experience.
Endpoint page
Title
Use short, clear titles that fit in one line on the table of contents (ToC). Follow the standard verb pattern:
Method | Verb | Example |
---|---|---|
POST | Create | Create an Account |
GET | List | List Accounts |
GET (by ID) | Retrieve | Retrieve an Account |
PATCH | Update | Update an Account |
DELETE | Delete / Deactivate | Delete an Account |
Description
Start with a clear and concise explanation of what the endpoint does and when to use it.
Prerequisites
List what is required to use the endpoint (e.g., authentication, permissions, required entities).
Parameters
Include all parameters, grouped by where they appear:
- Header parameters
- Path parameters
- Query parameters
Body (Payload)
Document all fields that appear in the request body.
Field | Type | Required | Description | Possible Values | Default | Constraints | Example |
---|---|---|---|---|---|---|---|
name | string | Yes | Name of the account | — | — | MaxLength: 100 | "Main Account" |
type | string | Yes | Account type | asset , liability | — | — | "asset" |
assetId | string | Yes | Associated asset ID | — | — | UUID | "01fbc1..." |
Success responses
Describe what users receive when the request is successful. Include status codes like 200
, 201
, or 204
.
Error Responses
All errors must follow Lerian’s standard error format. Include every possible error the endpoint can return.
Full error list
Create a separate page to group all possible error codes for each API/plugin. Divide them by HTTP status (e.g., 400, 404, 409, 500) and include a table with:
Code | Title | Message |
---|---|---|
0001 | Duplicate Ledger Error | A ledger with the name already exists in the division. |
0004 | Code Uppercase Requirement | The code must be in uppercase. |
TipCheck this example: Access Manager Error List
YAML File (Optional)
Whenever possible, add the OpenAPI spec (.yaml
) for this endpoint, following the OpenAPI 3.1 standard.
Updated 9 days ago