API Doc Standards — API document writing tablelevel
doc-writer agent API document quality tablelevel and pattern.
REST API document required section
1. overview — API purpose, target user, basic URL
2. authentication — authentication method, /
3. — request/ format, degree, error code
4. endpoint reference — by CRUD
5. error processing — error code ,
6. change capability — versionby changematters
endpoint document template
## POST /api/v1/users
user creation.
### request
****
| | | required |
|------|-----|------|
| Authorization | Bearer {token} | O |
| Content-Type | application/json | O |
**body text**
| | type | required | description | constraintcondition |
|------|------|------|------|---------|
| email | string | O | email | RFC 5322, 254specialist |
| name | string | O | name | 2~50specialist |
| role | string | X | role | admin/user/viewer, basic: user |
###
**nature (201 Created)**
{ "id": "usr_abc123", "email": "...", "name": "..." }
**error**
| status | code | description |
|------|------|------|
| 400 | INVALID_EMAIL | email |
| 409 | DUPLICATE_EMAIL | during email |
| 422 | VALIDATION_ERROR | nature |
error tablelevel
{
"error": {
"code": "RESOURCE_NOT_FOUND",
"message": "requestKorean number .",
"details": [{ "field": "user_id", "reason": "re-degree " }],
"request_id": "req_xyz789"
}
}
HTTP status code mapping
| scope |
un- |
usage code |
| 2xx |
nature |
200, 201, 204 |
| 4xx |
error |
400, 401, 403, 404, 409, 422, 429 |
| 5xx |
from error |
500, 502, 503 |
degree document tablelevel
from based (recommended)
| un- |
type |
basic |
description |
| limit |
integer |
20 |
item number (1~100) |
| cursor |
string |
- |
next degree from |
: has_more, next_cursor
based
| un- |
type |
basic |
description |
| page |
integer |
1 |
degree |
| per_page |
integer |
20 |
item number |
| sort |
string |
created_at |
standard |
| order |
string |
desc |
direction |
authentication section tablelevel
## authentication
all API request Bearer needed.
### : POST /auth/token
### usage: Authorization: Bearer {access_token}
### : POST /auth/refresh ( when)
| status code | cause | action |
|----------|------|------|
| 401 | / | re-grade |
| 403 | authority insufficient | role confirm |
Rate Limiting document tablelevel
|
limitation |
|
| Free |
100 |
minute |
| Pro |
1,000 |
minute |
| Enterprise |
10,000 |
minute |
: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
exceeding when: 429 + Retry-After
document tablelevel
- URL version:
/api/v1/, /api/v2/
- exchange: /endpoint/option un- addition
- exchange impossible: deletion, structure change, required un- addition → version needed
- basis example: minimum 6months before
document quality checklist
| item |
standard |
| examplewhen |
all endpoint request++error |
| type |
string, integer, boolean, array, object |
| required/optional |
all un- tablewhen |
| constraintcondition |
, , pattern |
| authentication |
endpointby needed authority |
| SDK example |
cURL + 1items or more |
| change capability |
date + change + impact scope |
1---2name: api-doc-standards3description: API document writing tablelevel and pattern library. doc-writer agent REST/GraphQL/gRPC API document writingto do when reference tablelevel. 'API document tablelevel', 'API reference writing' request when usage. However, OpenAPI Spec specialist creation API test execution scope outside.4---56# API Doc Standards — API document writing tablelevel78doc-writer agent API document quality tablelevel and pattern.910## REST API document required section1112```131. overview — API purpose, target user, basic URL142. authentication — authentication method, /153. — request/ format, degree, error code164. endpoint reference — by CRUD175. error processing — error code , 186. change capability — versionby changematters19```2021## endpoint document template2223```markdown24## POST /api/v1/users2526user creation.2728### request2930****31| | | required |32|------|-----|------|33| Authorization | Bearer {token} | O |34| Content-Type | application/json | O |3536**body text**37| | type | required | description | constraintcondition |38|------|------|------|------|---------|39| email | string | O | email | RFC 5322, 254specialist |40| name | string | O | name | 2~50specialist |41| role | string | X | role | admin/user/viewer, basic: user |4243### 4445**nature (201 Created)**46{ "id": "usr_abc123", "email": "...", "name": "..." }4748**error**49| status | code | description |50|------|------|------|51| 400 | INVALID_EMAIL | email |52| 409 | DUPLICATE_EMAIL | during email |53| 422 | VALIDATION_ERROR | nature |54```5556## error tablelevel 5758```json59{60 "error": {61 "code": "RESOURCE_NOT_FOUND",62 "message": "requestKorean number .",63 "details": [{ "field": "user_id", "reason": "re-degree " }],64 "request_id": "req_xyz789"65 }66}67```6869## HTTP status code mapping7071| scope | un- | usage code |72|------|------|----------|73| 2xx | nature | 200, 201, 204 |74| 4xx | error | 400, 401, 403, 404, 409, 422, 429 |75| 5xx | from error | 500, 502, 503 |7677## degree document tablelevel7879### from based (recommended)8081| un- | type | basic | description |82|---------|------|-------|------|83| limit | integer | 20 | item number (1~100) |84| cursor | string | - | next degree from |8586 : `has_more`, `next_cursor`8788### based8990| un- | type | basic | description |91|---------|------|-------|------|92| page | integer | 1 | degree |93| per_page | integer | 20 | item number |94| sort | string | created_at | standard |95| order | string | desc | direction |9697## authentication section tablelevel9899```markdown100## authentication101all API request Bearer needed.102103### : POST /auth/token104### usage: Authorization: Bearer {access_token}105### : POST /auth/refresh ( when)106107| status code | cause | action |108|----------|------|------|109| 401 | / | re-grade |110| 403 | authority insufficient | role confirm |111```112113## Rate Limiting document tablelevel114115| | limitation | |116|------|------|------|117| Free | 100 | minute |118| Pro | 1,000 | minute |119| Enterprise | 10,000 | minute |120121 : `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`122exceeding when: 429 + `Retry-After` 123124## document tablelevel125126- URL version: `/api/v1/`, `/api/v2/`127- exchange: /endpoint/option un- addition128- exchange impossible: deletion, structure change, required un- addition → version needed129- basis example: minimum 6months before130131## document quality checklist132133| item | standard |134|------|------|135| examplewhen | all endpoint request++error |136| type | string, integer, boolean, array, object |137| required/optional | all un- tablewhen |138| constraintcondition | , , pattern |139| authentication | endpointby needed authority |140| SDK example | cURL + 1items or more |141| change capability | date + change + impact scope |
revfactory