skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
dengineproblem/agents-monorepo57 installs

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-guide
view source ↗

Is 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'ы, параметры, ответы и крайние случаи
  • Тестируемость: Включайте рабочие примеры

Структура справочника

  1. Обзор — Назначение API, базовый URL, стратегия версионирования
  2. Аутентификация — Методы, токены, заголовки, примеры
  3. Endpoint'ы — Сгруппированные по ресурсам
  4. Обработка ошибок — Стандартные коды ошибок и ответы
  5. Ограничения частоты запросов — Лимиты, заголовки
  6. SDK и библиотеки — Доступные клиентские библиотеки
  7. Журнал изменений — История версий

Документация аутентификации

# 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.

Параметры:

ПараметрТипМестоОбязательныйОписание
idstringpathдаУникальный ID пользователя
includestringqueryнетСвязанные ресурсы через запятую

Пример запроса:

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 коды состояния:

КодСтатусОписание
200OKУспешный запрос
201CreatedРесурс создан
400Bad RequestОшибки валидации
401UnauthorizedНеверный/отсутствующий токен
403ForbiddenНедостаточно прав
404Not FoundРесурс не найден
429Too Many RequestsПревышен лимит запросов
500Internal 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

Лучшие практики

  1. Используйте последовательное именование (snake_case или camelCase)
  2. Включайте реалистичные примеры данных
  3. Показывайте примеры как успешных, так и ошибочных ответов
  4. Документируйте опциональные и обязательные параметры
  5. Включайте информацию об ограничениях частоты
  6. Используйте OpenAPI/Swagger спецификации
  7. Добавляйте уведомления о deprecation
  8. Тестируйте все примеры кода перед публикацией

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>