API-пайплайн: дать оракулу инструменты

Индекс: API-пайплайны — индекс

Цель: дать оракулу инструменты: описать свои HTTP-эндпоинты карточками и сохранить нужные им ключи как секреты, затем подключить и то и другое к агенде оракула.

Карточка API-эндпоинта — это один HTTP-вызов, который оракул может сделать; её operation_id — имя инструмента, её request_schema — аргументы инструмента. Секрет хранит ключ; эндпоинты ссылаются на него по имени, а значение подставляется только в момент вызова.

Шаги

1. Сохраните ключ.

POST /v0/my/secrets
Idempotency-Key: sec-0a9d…
{"key_name": "secret_shop_api_token", "value": "sk-example-123", "host": "api.example.com",
 "title": "Shop API token", "workspaces": ["470000000000000400"]}
→ {"nonce": "470000000000000410", "key_name": "secret_shop_api_token", "host": "api.example.com",
   "title": "Shop API token", "created_at": "…", …}

• key_name: secret_ + [a-z0-9_], 8–64 символа; принято secret_<name>_<role>.
• value только для записи: ни один вызов его не возвращает. Чтобы сменить, удалите секрет и создайте новый.
• host: значение отправляется только на этот хост. Указывайте его всегда.
• workspaces (обязательно, хотя бы один ваш): где хранится секрет.

2. Опишите эндпоинт.

POST /v0/my/api_endpoints
Idempotency-Key: ep-77b3…
{"title": "Check order status", "content": "Returns the status of one order. Use when a customer asks where their order is.",
 "operation_id": "orders_status", "method": "GET",
 "path": "https://api.example.com/v1/orders/{id}",
 "request_schema": {"type": "object", "properties": {"id": {"type": "string"}}, "required": ["id"]}}
→ {"nonce": "470000000000000420", "card_type": "api_endpoint", …}

• Обязательны: title, operation_id, method, path. method приводится к верхнему регистру (GET, POST, PATCH, PUT, DELETE).
• path: полный URL или путь, начинающийся с /, плюс domain (хост, куда идёт вызов).
• Ссылайтесь на секрет там, где сервис ждёт свой ключ, как {{secret_<key name>}} или по роли как {{secret_*_<role>}} (подключён должен быть ровно один секрет с этой ролью). Секреты, привязанные к разным хостам, нельзя смешивать в одном эндпоинте.
• content объясняет оракулу, когда его использовать; response_schema необязательна.

3. Подключите к агенде. PATCH /v0/my/agendas/{agenda} {"api_endpoints": ["470000000000000420"], "secrets": ["470000000000000410"]} — каждый список заменяет прежний. API-пайплайн: написать агенду для своих оракулов

4. Управление.

• Эндпоинты: PATCH /v0/my/api_endpoints/{nonce} (любое поле выше, handle, видимость), DELETE …, GET /v0/my/api_endpoints, публичные — GET /v0/graph/api_endpoints (+ /{nonce}).
• Секреты: GET /v0/my/secrets (имена и хосты, никогда значения), PATCH /v0/my/secrets/{nonce} (title, content, host, видимость), DELETE /v0/my/secrets/{nonce}.

За кадром

• Значение секрета расшифровывается только когда оракул вызывает эндпоинт, и уходит только на хост секрета.
• Тот, кому вы дали write на эндпоинт, может править его текст, но не может менять, куда он отправляет, или добавлять ссылки на секреты; только владелец меняет domain, host, видимость и права.

Правила

• 400: title is required; operation_id, method and path are required; value is required; a secret must be placed into a workspace; имя ключа: must start with secret_, length must be 8..=64, only [a-z0-9_] allowed.
• 403: only the card owner can change where the endpoint sends; only the card owner can add secret references: …; поля владельца, изменённые получателем гранта.
• В момент вызова отсутствующая или неоднозначная роль секрета либо секреты, привязанные к разным хостам, останавливают вызов.

Поверхность API