API Documentation Template

Use this template when documenting REST API endpoints manually (for endpoints not auto-generated by OpenAPI/Swagger).

---

Endpoint Name

Brief one-sentence description of what this endpoint does.

HTTP Request

METHOD /api/v1/resource/{parameter}

Description

Detailed description of the endpoint's functionality, use cases, and behavior.

Authentication

Required authentication method:

• Type: JWT Bearer Token
• Scope: read:stocks (or applicable scope)

Path Parameters

Parameter	Type	Required	Description
parameter	string	Yes	Description of the parameter

Query Parameters

Parameter	Type	Required	Default	Description
limit	integer	No	20	Number of results (max: 100)
offset	integer	No	0	Pagination offset
sort_by	string	No	created_at	Field to sort by

Request Headers

Header	Required	Description
Authorization	Yes	JWT Bearer token
Content-Type	Yes	application/json

Request Body

info

Include this section only for POST, PUT, PATCH requests

{
  "field1": "value1",
  "field2": 123,
  "nested": {
    "field3": true
  }
}

Schema:

Field	Type	Required	Description
field1	string	Yes	Description of field1
field2	integer	No	Description of field2
nested.field3	boolean	No	Description of nested field

Response

Success Response (200 OK):

{
  "status": "success",
  "data": {
    "id": "12345",
    "name": "Example Resource",
    "created_at": "2025-11-13T10:30:00Z"
  },
  "metadata": {
    "total": 100,
    "limit": 20,
    "offset": 0
  }
}

Response Schema:

Field	Type	Description
status	string	Response status ("success" or "error")
data	object	Response payload
data.id	string	Unique identifier
data.name	string	Resource name
data.created_at	string	ISO 8601 timestamp
metadata	object	Pagination metadata

Error Responses

400 Bad Request:

{
  "status": "error",
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "The 'limit' parameter must be between 1 and 100",
    "field": "limit"
  }
}

401 Unauthorized:

{
  "status": "error",
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired authentication token"
  }
}

404 Not Found:

{
  "status": "error",
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Resource with ID '12345' not found"
  }
}

429 Too Many Requests:

{
  "status": "error",
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again in 60 seconds",
    "retry_after": 60
  }
}

Common Error Codes:

Code	HTTP Status	Description
INVALID_PARAMETER	400	Request parameter validation failed
UNAUTHORIZED	401	Missing or invalid authentication
FORBIDDEN	403	Insufficient permissions
RESOURCE_NOT_FOUND	404	Requested resource doesn't exist
RATE_LIMIT_EXCEEDED	429	Too many requests
INTERNAL_ERROR	500	Server error

Rate Limiting

• Free Tier: 100 requests/hour
• Pro Tier: 500 requests/hour
• Enterprise: 2,000 requests/hour

Rate limit headers returned:

• X-RateLimit-Limit: Maximum requests per hour
• X-RateLimit-Remaining: Remaining requests
• X-RateLimit-Reset: Unix timestamp when limit resets

Examples

cURL:

curl -X GET \
  'https://api.screener.kr/api/v1/stocks?limit=10&sort_by=volume' \
  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \
  -H 'Content-Type: application/json'

Python:

import requests

url = "https://api.screener.kr/api/v1/stocks"
headers = {
    "Authorization": "Bearer YOUR_JWT_TOKEN",
    "Content-Type": "application/json"
}
params = {
    "limit": 10,
    "sort_by": "volume"
}

response = requests.get(url, headers=headers, params=params)
data = response.json()

print(f"Found {data['metadata']['total']} stocks")
for stock in data['data']:
    print(f"- {stock['name']} ({stock['ticker']})")

TypeScript:

const response = await fetch(
  'https://api.screener.kr/api/v1/stocks?limit=10&sort_by=volume',
  {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${jwtToken}`,
      'Content-Type': 'application/json'
    }
  }
);

const data = await response.json();

console.log(`Found ${data.metadata.total} stocks`);
data.data.forEach((stock: Stock) => {
  console.log(`- ${stock.name} (${stock.ticker})`);
});

Notes

Best Practices

• Cache responses when possible to reduce API calls
• Implement exponential backoff for rate limit errors
• Always validate input parameters client-side before sending requests

warning

• This endpoint returns cached data updated every 5 minutes
• Large result sets (>1000 items) should use pagination
• Historical data is retained for 5 years only

See Also

• Authentication Guide
• Rate Limiting Documentation
• Error Handling Best Practices

---

Last Updated: [Date] API Version: v1