Разработка API

Переход от требований к API

Как и большинство технологий, API — это решение проблемы. Чтобы спроектировать правильный API, вам необходимо убедиться, что решаемая вами задача четко определена, ответив на следующие вопросы:

• Кто является целевыми потребителями этого API?
• Какого рода информацией потребители будут манипулировать через API?
• Какие действия потребители будут выполнять с API?

Например, если вы компания по доставке еды, вам может понадобиться создать API для своей партнерской сети, который позволит им просматривать базу данных ресторанов, для которых вы предоставляете услуги доставки, и выполнять в ней поиск.

В этом примере ваш API ориентирован на партнеров вашей компании. Им понадобится обрабатывать данные о ресторанах и выполнять поисковые запросы по этим данным, с определенными возможностями фильтрации и сортировки.

Другой пример: если вы — SaaS-компания, разрабатывающая календарный сервис, вам может потребоваться создать API, чтобы другие фронтенд-разработчики со всего мира могли создавать новые мобильные и веб-приложения на базе вашей календарной системы.

Забота о пользователях вашего API — это первый шаг к тому, чтобы обеспечить им качественный опыт разработчика. Это поможет вашему API выделиться и повысить уровень вовлеченности.

Элементы, составляющие API

При проектировании API используются четыре ключевые концепции:

• Ресурс — это элемент, с которым ваши потребители будут взаимодействовать через ваш API. Ресурсы однозначно идентифицируются с помощью пути, который в сочетании с конечной точкой API обеспечивает уникальный адрес ресурса в Интернете. Например, Calendars — это имя ресурса, соответствующего списку календарей, а его путь — /calendars.
• Операция — это действие, которое можно выполнить над вашими ресурсами. Наиболее распространенными операциями являются GET (чтение), POST (создание), PUT (обновление) и DELETE. Например, List all Calendars — это название операции, которая использует метод GET для ресурса Calendars.
• Тип данных — это описание фактических данных, передаваемых по сети. Например, Calendar — это имя типа данных, который будет описывать все свойства календаря, такие как его имя, владелец и ссылка на принадлежащие ему события. Операция List all Calendars возвращает список типов данных Calendar.
• Компонент — это элемент, который можно повторно использовать во всем определении API. Например, если вам необходимо использовать один и тот же параметр запроса в нескольких операциях, вы можете создать его как компонент и ссылаться на него в стольких операциях, сколько потребуется.

Существуют и другие полезные элементы, составляющие API:

• Эндпоинт — это основная точка входа для вашего API в Интернете. Конечная точка состоит из схемы, такой как HTTPS, и хоста, такого как www.calendar-api.com.
• Блок Текст можно использовать для свободного ввода любого текста (включая Markdown), который можно разместить в любом месте вашего дизайна API. Используйте текстовые блоки для объяснения сквозных тем, таких как аутентификация и обработка ошибок.
• Раздел используется для логической группировки ресурсов и типов данных. Используйте их, чтобы сделать дизайн вашего API более понятным и удобным для разработчиков. Вы можете перетащить элементы в разделы на левой панели, а также изменять порядок разделов относительно друг друга.

В Контрактах API вы сможете создавать эти элементы с помощью меню Создать новый в правом верхнем углу.

URL-адреса серверов создаются на экране общих сведений. URL-адрес сервера может иметь статус Опубликован или Не опубликован. Если он опубликован, он отображается в Live Documentation.