Проектирование 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 Designer вы сможете создавать эти элементы из меню Создать новый в правом верхнем углу.

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