api-reference-guide
Эксперт по API reference документации. Используй для создания справочников по API, описания endpoints и примеров запросов.
How do I install this agent skill?
npx skills add https://github.com/dengineproblem/agents-monorepo --skill api-reference-guideIs this agent skill safe to install?
- Gen Agent Trust Hubfail
The skill is a template and instructional guide for creating API documentation. It contains no executable code or malicious patterns. The automated security alert for 'client.Do' is a false positive, as it is a standard Go method call (http.Client.Do) used within a documentation example rather than a malicious URL.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerwarn
1/1 file flagged
What does this agent skill do?
API Reference Guide Creator
Эксперт в создании комплексной документации по API, которую разработчики обожают использовать.
Основные принципы
- Подход "разработчик прежде всего": Пишите с точки зрения того, кто внедряет API
- Ясность важнее краткости: Предоставляйте достаточно деталей
- Последовательность: Используйте единообразные паттерны
- Полнота: Покрывайте все endpoint'ы, параметры, ответы и крайние случаи
- Тестируемость: Включайте рабочие примеры
Структура справочника
- Обзор — Назначение API, базовый URL, стратегия версионирования
- Аутентификация — Методы, токены, заголовки, примеры
- Endpoint'ы — Сгруппированные по ресурсам
- Обработка ошибок — Стандартные коды ошибок и ответы
- Ограничения частоты запросов — Лимиты, заголовки
- SDK и библиотеки — Доступные клиентские библиотеки
- Журнал изменений — История версий
Документация аутентификации
# API Key Authentication
curl -X GET "https://api.example.com/v1/users" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json"
// JavaScript SDK Example
const client = new APIClient({
apiKey: 'your-api-key',
baseURL: 'https://api.example.com/v1'
});
Формат документации endpoint'ов
GET /users/{id}
Получить конкретного пользователя по ID.
Параметры:
| Параметр | Тип | Место | Обязательный | Описание |
|---|---|---|---|---|
| id | string | path | да | Уникальный ID пользователя |
| include | string | query | нет | Связанные ресурсы через запятую |
Пример запроса:
curl -X GET "https://api.example.com/v1/users/12345?include=profile,settings" \
-H "Authorization: Bearer YOUR_API_KEY"
Ответ (200 OK):
{
"id": "12345",
"email": "user@example.com",
"created_at": "2023-01-15T10:30:00Z",
"profile": {
"first_name": "John",
"last_name": "Doe"
}
}
POST /users
Создать новый аккаунт пользователя.
Тело запроса:
{
"email": "string (обязательный)",
"password": "string (обязательный, минимум 8 символов)",
"profile": {
"first_name": "string (опциональный)",
"last_name": "string (опциональный)"
}
}
Ответ (201 Created):
{
"id": "12346",
"email": "newuser@example.com",
"created_at": "2024-01-15T14:30:00Z"
}
Документация ошибок
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid request parameters",
"details": [
{
"field": "email",
"message": "Email address is required"
}
],
"request_id": "req_1234567890"
}
}
HTTP коды состояния:
| Код | Статус | Описание |
|---|---|---|
| 200 | OK | Успешный запрос |
| 201 | Created | Ресурс создан |
| 400 | Bad Request | Ошибки валидации |
| 401 | Unauthorized | Неверный/отсутствующий токен |
| 403 | Forbidden | Недостаточно прав |
| 404 | Not Found | Ресурс не найден |
| 429 | Too Many Requests | Превышен лимит запросов |
| 500 | Internal Server Error | Ошибка сервера |
Примеры на разных языках
Python
import requests
headers = {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
}
response = requests.get(
'https://api.example.com/v1/users/12345',
headers=headers
)
print(response.json())
Node.js
const fetch = require('node-fetch');
const response = await fetch('https://api.example.com/v1/users/12345', {
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
}
});
const data = await response.json();
console.log(data);
Go
req, _ := http.NewRequest("GET", "https://api.example.com/v1/users/12345", nil)
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
Типы данных и схемы
User:
type: object
properties:
id:
type: string
description: Unique user identifier
example: "usr_1234567890"
email:
type: string
format: email
description: User's email address
created_at:
type: string
format: date-time
description: ISO 8601 timestamp
status:
type: string
enum: [active, inactive, suspended]
description: Current account status
Продвинутые возможности
Фильтрация
GET /users?filter[status]=active&filter[role]=admin
Пагинация
GET /users?page=2&limit=20
Response headers:
X-Total-Count: 150
X-Page: 2
X-Per-Page: 20
Link: <https://api.example.com/v1/users?page=3>; rel="next"
Сортировка
GET /users?sort=-created_at,email
Минус означает сортировку по убыванию.
Выбор полей
GET /users?fields=id,email,created_at
Идемпотентность
curl -X POST "https://api.example.com/v1/payments" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: unique-request-id-123" \
-d '{"amount": 1000}'
Rate Limiting Headers
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200
Лучшие практики
- Используйте последовательное именование (snake_case или camelCase)
- Включайте реалистичные примеры данных
- Показывайте примеры как успешных, так и ошибочных ответов
- Документируйте опциональные и обязательные параметры
- Включайте информацию об ограничениях частоты
- Используйте OpenAPI/Swagger спецификации
- Добавляйте уведомления о deprecation
- Тестируйте все примеры кода перед публикацией
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/dengineproblem/agents-monorepo/api-reference-guide">View api-reference-guide on skillZs</a>