Skip to content

Глоссарий для любых API и языков #607

Open

Description

@bim-ba

Сейчас у слова «операция» в коде семь значений, у «surface» в русских доках - три перевода. Глоссарий, построенный только на Яндексе и Python, не подойдет ни GraphQL, ни Go.

Вопрос

Утвердить глоссарий, который одинаково описывает любой API и любой язык. Решать после бенчмарка «язык × API» - он покажет, какие слова нужны на GitHub, Stripe, Slack и в Go.

Черновик

слово значение не говорить
операция то, что вызывает пользователь: метод SDK, команда CLI, инструмент MCP; одно имя на всех поверхностях и языках endpoint, ручка (слово «метод» - только про HTTP-метод)
запрос то, что уходит по сети: метод, адрес, параметры, тело вызов, call
задание долгая работа на стороне сервиса, которую ждут или опрашивают операция (у Яндекса - Operation)
поверхность SDK, CLI или MCP; поверхностей три, а плагин и образ - каналы поставки способ, слой, surface
каталог OpenAPI 3.1 плюс x-ycli-*, все, что читает генератор spec, описание
ядро рукописная библиотека языка, на которой стоит сгенерированный код runtime, core

Рекомендую: утвердить после бенчмарка с правками, которые он покажет. Черновик на английском (glossary-draft.md в материалах ревью) станет GLOSSARY.md.
Против: «операция» у Яндекса уже значит «задание». Пользователь DataLens увидит одно слово в двух смыслах.

Ответ одной строкой: «да» или правки по строкам.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    needs:decisionWaiting for an owner decisionpriority:nextDo after the current workwayfinder:grillingWayfinder ticket: a decision settled in conversation with the owner

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions