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

Автор материала — @alitvinenko

Версионность

С самого начала разработки вашего API, каким бы маленьким оно вам ни казалось, закладывайте в архитектуре возможность версионирования. Если не хотите сразу писать код для поддержки версионности, то хотя бы договоритесь о том, КАК вы будете это делать в будущем. Как минимум, вам нужно быть к этому готовыми.

Определите срок поддержки устаревших версий

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

Помните о старых клиентах

Всегда помните о том, что вашим API могут пользоваться старые клиенты, которые не знают ничего о том, что вы что-то могли поменять в своих методах. Особенно актуально это при создании API для мобильных клиентов. Если вы меняете какую-то логику работы методов, лучше это делать через создание новой версии этого метода, чем менять в текущем. Изменять текущий метод допустимо только в том случае, когда это не повлияет на входящие и исходящие параметры. То есть если вы меняете не сам метод, а какую-то логику глубоко внутри кода.

Соблюдайте единообразие в названиях методов, параметров

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

Плохой пример

GET https://api.example.com/product/list - API-метод получения списка продуктов

GET https://api.example.com/offers - API-метод получения товарных предложений

Как видно из примера, в одном случае список мы запрашиваем по урлу, где объект назван в единственном числе, далее следует слово list, а во втором примере объект просто назван во множественном числе. Вообще, и тот, и другой метод понятны сразу, но в данном случае было бы правильно использовать везде или множественное число, или /list

Хороший пример

GET https://api.example.org/products

GET https://api.example.org/offers

Используйте одинаковые названия входящих параметров

Разработчикам, использующим ваше API будет гораздо легче, если вы будете придерживаться единообразия в названии ваших параметров API. Это касается параметров, которые каким-либо образом фильтруют результаты или, например, задают порядок сортировки.

Договоритесь о базовых структурах, которые могут быть в ответах

Сразу договоритесь о том, какие базовые форматы ответов будут у вашего API, и далее неукоснительно следуйте этим договоренностям.

Обычно во всех API запросы можно поделить на три вида

Получение информации о каком-то конкретном объекте
Получение информации о нескольких однотипных объектах (список)
Выполнение каких-либо действий над объектом или объектами. Ваше API должно быть реализовано таким образом, чтобы каждый метод, отнесенный к одной из трех перечисленных групп, возвращался в схожей структуре.

Например, методы из первой группы всегда могут возвращать данные в следующей структуре:

{
    "result": <object>
}

Список может возвращаться в таком виде:

{
    "items": [
        <object>,
        <object>,
        ...
    ],
    "count": (int),
    "limit": (int),
    "offset": (int)
}

А API-метод действия над объектом или объектами может возвращать или 200 код с пустым телом или, например, модифицированный объект (как в первом примере).

Примите единый формат возврата ошибок

Этот пункт можно было включить в предыдущий, но он нам кажется настолько важным, что решили описать его отдельно. Проектируйте ваш API таким образом, чтобы все методы возвращали ошибки в едином стиле и в едином формате. Будет очень плохо, если одни методы будут возвращать http-код 400 Bad request с пустым телом, а другие методы будут возвращать, например, 200 OК и в теле ответа будет информация об ошибке.

Сделайте удобным отдачу списка объектов

Обратите внимание на пример отдачи списка из предыдущего пункта. Там помимо самого списка возвращается еще и вспомогательная информация о том, сколько всего объектов найдено по данному запросу, сколько было запрошено объектов и каков был отступ от первого результата. Такой способ отдачи списка позволяет сильно упростить жизнь разработчиков, которые будут работать с вашим API. Они всегда смогут построить «дозагрузку списка» или «постраничную навигацию».

Указанный в примере способ не является единственно верным. Также можно использовать, например, параметр hasnextpage, означающий, есть ли смысл выполнять следующий запрос. Главное, чтобы разработчики, использующие ваш API, не должны были делать лишний запрос на получение списка.

Пишите документацию

Да, ни для кого не секрет, что никто не любит писать документацию. Но писать ее нужно обязательно.

Документацию можно поделить на два вида:

Внутренняя документация. В ней желательно описать все договоренности: codestyle, соглашения по именованию методов, параметров, форматы ответов и запросов и т.д. Этот вид документации, как минимум, поможет быстрее вливаться в работу новым разработчикам.
Публичная документация. Даже если вашим API будет пользоваться соседний отдел, его все равно нужно описывать. Здесь нужно описать форматы ответов, как правильно обрабатывать ошибки и т.п. Будет очень хорошо, если у вас будет документация на сами методы вашего API.
Хорошо, если для каждого метода вы будете указывать:
- Пример запроса;
- Краткое описание того, что происходит в этом методе;
- Описание входящих параметров (тип, название, обязательный или нет, краткое описание если нужно);
- Пример ответа;
- Описание каждого поля в ответе (название, тип, описание). Такую документацию можно или писать «руками» или использовать различное ПО, помогающее решить данную задачу, — например swagger. Крайне важно поддерживать вашу документацию актуальной в любой момент времени. Лучше за этим следить постоянно, так как потом будет очень трудно привести ее в надлежащий вид.

Предсказуемость действий

Проектируйте методы API таким образом, чтобы они были понятны даже по своему урлу. Названия методов должны быть максимально информативными. Например, метод, отдающий информацию о пользователе, не должен его модифицировать. Конечно, в любой системе и в любых правилах могут быть исключения. Но тогда это должно быть четко указано в документации.

Единый формат авторизации и передачи авторизационных данных

В рамках одного сервиса API у вас должен быть единый формат передачи авторизационных данных.

Тесты

Вы могли заметить, что почти все наши рекомендации относятся к подготовительной фазе. И это говорит о том, что, прежде чем что-либо разрабатывать, необходимо уделить время на проектирование, подготовку «плацдарма», так сказать. Это позволит вам в будущем экономить время при разработке. А также это поможет пользователям API в его интеграции.

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

Некоторые советы по созданию API