A
API
Application Programming Interface. Позволяет различным системам взаимодействовать друг с другом программно. Два типа API - это REST API (веб-API) и API нативной библиотеки.
Api console
Интерактивный дисплей для спецификации RAML. Похож на Swagger UI, но для RAML.
Apimatic
Поддерживает большинство форматов описания REST API (OpenAPI, RAML, API Blueprint и т. Д.) И обеспечивает генерацию кода SDK, преобразования из одного формата спецификации в другой и многие другие службы. APIMATIC «позволяет вам определять API и генерировать SDK для более чем 10 языков». Например, можно автоматически конвертировать Swagger 2.0 в 3.0, используя сервис API Transformer на этом сайте. СМ. https://apimatic.io/ и их документацию.
API Transformer
Кроссплатформенный сервис, предоставляемый APIMATIC, который автоматически преобразует ваш документ спецификации из одного формата или версии в другой. См. apimatic.io/transformer.
Apiary
Платформа, поддерживающая полный жизненный цикл проектирования, разработки и развертывания API. Для интерактивной документации Apiary поддерживает спецификацию API Blueprint, которая похожа на OpenAPI или RAML, но содержит больше элементов Markdown. Он также теперь поддерживает спецификацию OpenAPI. См apiary.io.
Api Blueprint
Спецификация API Blueprint является альтернативой спецификации OpenAPI или RAML. API Blueprint написан с использованием синтаксиса Markdown. См. API Blueprint.
Apigee
Подобно Apiary, Apigee предоставляет услуги по управлению всем жизненным циклом API. В частности, Apigee позволяет «управлять сложностью и рисками API в мире с несколькими и гибридными облаками, обеспечивая безопасность, видимость и производительность во всей среде API». Поддерживает спецификацию OpenAPI. См. apigee.com.
Asciidoc
Облегченный текстовый формат, который обеспечивает больше семантических функций, чем Markdown. Используется в некоторых генераторах статических сайтов, таких как Asciidoctor или Nanoc. См asciidoc.org.
B
Branch
В Git branch (ветвь) - это копия репозитория, которая часто используется для разработки новых функций. Обычно вы работаете в ветках, а затем сливаете свою ветку в основную. См git-branch.
C
Clone
В Git clone - это команда, используемая для копирования хранилища таким образом, чтобы оно было связано с оригиналом. Первый шаг в работе с любым репозиторием - локальное клонирование репо. Git - это распределенная система контроля версий, поэтому каждый, кто работает в ней, имеет локальную копию (клон) на своих машинах. Центральный репозиторий называется источником. Каждый пользователь может извлекать обновления из источника и отправлять обновления в источник. См git-clone.
Commit
В Git commit - это снимок ваших изменений в репо. Git сохраняет коммит как снимок во времени, к которому вы можете вернуться позже, если это необходимо. Вы фиксируете свои изменения перед извлечением из источника или перед объединением своей ветви с другой веткой. См. git-commit.
CRUD
Create, Read, Update, Delete. Эти четыре операции программирования часто сравнивают с POST, GET, PUT и DELETE в REST API.
curl
curl - это утилита командной строки, которая позволяет выполнять HTTP-запросы с различными параметрами и методами. Командную строку можно использовать вместо перехода к веб-ресурсам в адресной строке браузера, чтобы получить те же ресурсы, извлеченные в виде текста.
E
Endpoints and methods
Эндпоинты (конечные точки) показывают как достичь ресурса, в то время как методы указывают на разрешенные действия (GET, POST, DELETE и другие) с ресурсом.
Один и тот же ресурс может иметь множество связанных эндпоинтов, каждая из которых имеет разные пути, методы и возвращает разную информацию об одно и том же ресурсе. Эндпоинты могут иметь краткое описание, схожее с описанием ресурса. Кроме того, эндпоинт показывает только конечный путь URL ресурса, без базового пути, общего для всех эндпоинтов.
G
GitLab
Платформа управления репозиториями кода, используемая разработчиками компании.
Git Repo
Репозиторий git хранит код проекта. Хранятся только недвоичные (читаемые человеком) текстовые файлы в репозитории, потому что Git может запускать diff для текстовых файлов и показывать изменения.
Gulp
Gulp — это инструмент сборки веб-приложения, позволяющий автоматизировать повторяющиеся задачи, такие как сборка и минификация CSS- и JS-файлов, запуск тестов, перезагрузка браузера и т.д. Тем самым Gulp ускоряет и оптимизирует процесс веб-разработки. В статье мы рассмотрим основы использования этого инструмента.
H
HAT
Help Authoring Tool. Относится к традиционным инструментам разработки справки (RoboHelp, Flare, Author-it и т. Д.), используемым техническими писателями для документации. Инструменты для API-документации, как правило, используют инструменты docs-as-code вместо HAT.
HATEOS
Аббревиатура Hypermedia as the Engine of Application State (гипермедиа как двигатель состояния приложения). Гипермедиа - это одна из характеристик REST, которая часто упускается из виду или отсутствует в REST API. В ответах API ответы, охватывающие несколько страниц, должны предоставлять пользователям ссылки на другие элементы.
Header parameters
Параметры, которые включены в заголовок запроса, обычно в header передаются параметры авторизации.
J
JSON
JavaScript Object Notation. Облегченный синтаксис, содержащий объекты и массивы, обычно используемый (вместо XML) для возврата информации из REST API. http://www.json.org/
M
Method
Разрешенная операция с ресурсом: GET, POST, PUT, DELETE. Эти операции определяют, читаете ли вы информацию, создаете новую, обновляете существующую или удаляете информацию.
O
OAS
Аббревиатура OpenAPI Specification
OpenAPI
Официальное название для спецификации OpenAPI. Спецификация OpenAPI предоставляет набор свойств, которые можно использовать для описания REST API. При валидности спецификации, ее можно использовать для создания интерактивной документации, создания клиентских SDK, запуска модульных тестов и многого другого. Подробности спецификации на GitHub. В рамках инициативы Open API с Linux Foundation спецификация OpenAPI направлена на то, чтобы быть независимой от производителя.
OpenAPI contract
Синоним термина “Спецификация OpenAPI”
OpenAPI specification
Файл в формате YAML или JSON с описанием REST API. Следует формату спецификации OpenAPI. openapis.org
P
Parameters
Параметры - это данные, которые можно передать конечной точке (например, указать формат ответа или возвращаемую сумму), чтобы повлиять на ответ. Существует четыре типа параметров: параметры заголовка, параметры пути, параметры строки запроса и параметры тела запроса.
Различные типы параметров часто документируются в отдельных группах на одной странице. Не все конечные точки могут содержать все типы параметра.
Path parameters
Параметры, которые отображаются в пути эндпоинта, перед строкой запроса и отделяются знаком ?. Параметры пути обычно устанавливаются в фигурных скобках.
pull
Извлечение данных.
В Git, при извлечении данных из источника (главное место, где вы клонировали репо), вы получаете последние обновления в локальную систему. При запуске git pull, Git сохраняет обновления из источника в локальную копию. Если слияние не может произойти автоматически, будут отображаться конфликты слияния. Git-pull.
Pull request
Pull request - запрос от внешнего участника на слияние клонированную ветки обратно в master ветку. Рабочий процесс pull request используется в проектах, поскольку разработчики вне группы обычно не имеют прав участника для слияния обновлений в хранилище. Gitlab предоставляет удобный интерфейс для создания и обработки таких запросов. Pull request
push
Отправка изменений.
В Git, для отправки изменений в источник последних обновлений из локальной копии, выполняется команда git push. Обновления синхронизируют локальную копии с удаленным репо. git push.
Q
Query string parameters
Параметры, которые отображаются в конечной точки после знака ?
R
Repo
Инструмент для консолидации и управления множеством мелких репо с помощью одной системы. git-repo.
request
Запрос. Способ, получения информации, возвращаемой API. В запросе клиент предоставляет URL ресурса с соответствующей авторизацией серверу API. API возвращает ответ с запрошенной информацией.
request body parameters
Параметры в теле запроса, прописываются в формате JSON.
response
Информация, возвращаемая API после выполнения запроса. Ответы обычно представлены в формате JSON или XML.
response example and schema
response example показывает пример ответа из примера запроса; Схема ответа определяет все возможные элементы в ответе. Пример ответа не является исчерпывающим для всех конфигураций параметров или операций, но он должен соответствовать параметрам, переданным в примере запроса. Ответ позволяет разработчикам узнать, содержит ли ресурс информацию, которую они хотят, формат и то, как эта информация структурирована и помечена.
Описание ответа является схемой ответа. Схема ответа документирует ответ более полным, общим способом, перечисляя каждое возвращаемое свойство, что содержит каждое свойство, формат данных значений, структуру и другие подробности.
resource description
«Ресурсы» относятся к информации, возвращаемой API. Большинство API имеют различные категории информации или различные ресурсы, которые могут быть возвращены.
Описание ресурса краткое (1-3 предложения) и обычно начинается с глагола. Ресурсы обычно имеют различные конечные точки для доступа к ресурсу и несколько методов для каждой конечной точки. На странице отдельного ресурса обычно описывается и общий ресурс, а также описывается ряд конечных точек для доступа к ресурсу.
REST API
Аббревиатура Representational State Transfer. Использует веб-протоколы (HTTP) для отправки запросов и предоставления ответов независимо от языка, что означает, что пользователи могут выбирать любой язык программирования, который они хотят совершать при вызовах.
S
SDK
Software development kit - Комплект для разработки программного обеспечения. Разработчики часто создают SDK для сопровождения REST API. SDK помогает разработчикам реализовать API с использованием определенного языка, например Java или PHP.
Swagger
Swagger является одним из инструментов API, связанным со спецификацией OpenAPI. Некоторые из этих инструментов включают Swagger Editor, Swagger UI, Swagger Codegen, SwaggerHub и другие. Этими инструментами управляет Smartbear. Дополнительная информация: Swagger Tools. «Swagger» был оригинальным названием спецификации OpenAPI, но позже имя было изменено на OpenAPI, чтобы усилить открытый, не составляющий собственность характер стандарта.
Swagger Codegen
Генерирует код SDK клиента для множества различных языков (таких как Java, JavaScript, Scala, Python, PHP, Ruby, Scala и другие). Код SDK клиента помогает разработчикам интегрировать API на конкретной платформе и обеспечивает более надежные реализации, которые могут включать в себя масштабирование, многопоточность и другой необходимый код. Swagger Codegen генерирует клиентские SDK практически на каждом языке программирования. Дополнительная информация на Swagger Codegen.
Swagger Editor
Онлайн-редактор, который проверяет документацию OpenAPI на соответствие правилам спецификации OpenAPI. Редактор Swagger помечает ошибки и дает советы по форматированию. Swagger Editor
Swagger UI
Веб-фрэймворк с открытым кодом, который парсит спецификацию OpenAPI и генерирует интерактивную страницу сайта с документацией. Swagger UI является инструментом, трансформирует спецификацию в сайт вида Petstore
SwaggerHub
Сайт, разработанный Smartbear, с целью помочь командам совместно работать над спецификацией OpenAPI. Помимо создания интерактивной документации из SwaggerHub, можно создавать множество клиентских и серверных SDK и других сервисов.
V
VCS
Аббревиатура version control system. Пример Git и Mercurial
Version control system
Система управления кодом, основанная на коммитах (снимках), которое хранят контент в определенных состояниях. Позволяет вернуться к предыдущим состояниям, разделять код на разные версии, ветки и т.д.
Y
YAML
Рекурсивная аббревиатура «YAML Ain’t No Markup Language». Человекочитаемый, чувствительный к пространству синтаксис, используемый в документации спецификации OpenAPI.