Best Practices, которые стоит использовать при проектировании REST API
1. Endpoint'ы - это существительное, а не глагол. Это одна из самых распространенных ошибок, которые я когда либо встречал (и сам совершал, естественно). Например, было в моей практике и такое - POST /generateMultipleDocument.
Тут важно понимать, что метод - это уже глагол и еще раз дублировать его в наименовании эндпоинта не нужно.
В идеале, в данном варианте будет POST /documents
2. Используйте множественное число. В большинстве случаев (в 99%), при проектировании методов, работающих с вашим ресурсом - эти методы будут работать не с единственный экземпляром этого ресурса, поэтому название эндпоинта должно быть во множественном числе.
Если же нужно указать, что из всего массива экземпляров ресурса вам нужно получить\обновить\удалить какой-то конкретный, то помещайте идентификатор этого ресурса в URL, передавая его в path.
Например, вот так:
/documents
/documents/{documentId}
Вместо:
/document
/document/{documentId}
В любом случае, если вы уже начали делать в каком-то из этих двух стилей, то продолжайте делать в нем, потому что смешивать их - еще более плохая идея.
3. Не забывайте про версионирование микросервиса. Почти любой сервис с течением времени развивается и обрастает все большим количеством функций. Если сервис при создании получил версию 1.0.0, то при добавлении какой-нибудь логики в него, добавлении нового метода или полного рефакторинга - версия должна измениться.
Например:
host/v1/documents вместо host/v1/documents после внесения мажорной доработки. Основные правила версионирования - в случае, если меняется логика незначительно, не добавляется/изменяется обязательность атрибутов, то инкрментируется минорная версия.
В случае если был полный рефакторинг, менялись обязательные параметры (например, добавил новый атрибут, который является обязательным), иногда при добавлении нового метода - инкрементируется мажорная версия (в этом случае, все подписанты вашего микросервиса должны в обязательном порядке переехать на новую версию вашего микросервиса, иначе они не смогут взаимодействовать с ним.
Однако, это не всегда обязательно, т.к. мы же работаем с микросервисами и достаточно гибки - в случае, если появляется такая мажорная доработка, но ваши подписанты не готовы дорабатываться одновременно с вами - вы можете выкатить одновременно две версии микросервиса, v1 и v2 и поддерживать их обе. Это несет определенные неудобства и затраты, конечно, но в любом случае лучше, чем допускать неработоспособность интеграции. В дальнейшем, когда все ваши подписанты доработаются - поддержку предыдущей версии можно остановить.
Примечание: структура версионирования такова: первая цифра - это мажор, вторая цифра - это минор, третья цифра - это патч. Про первые две я уже сказал, а последняя используется только разработчиками. Насколько я понимаю, она повышается вообще каждый раз когда вносят изменения в сервис, но тут могу быть не точен.
4. Используйте пагинацию. Отправка большого объема данных через HTTP не очень хорошая идея. Безусловно, возникнут проблемы с производительностью, особенно на фронте, если вы туда вернете огромную портянку-JSON. Best practice является разбиение результатов на части, а не отправка всех записей сразу.
5. Используйте коды ответов HTTP правильно и эффективно.
Не просто так их огромное количество (https://developer.mozilla.org/ru/docs/Web/HTTP/Status). Все знать и использовать не обязательно, но вот что вас точно отличит в лучшую сторону, если вы будете это использовать:
5.1 Использовать 201 "Created", вместо 200 "OK", в случае если вы в POST действительно создаете какой-то ресурс. Используется только в POST!
5.2 Использовать 204 "No Content", вместо 200 "OK" для DELETE. Это ответ на успешный запрос и он не будет возвращать тело, что и не нужно для данного метода.
5.3 Не забывайте использовать 401 "Unauthorized", 403 "Forbidden" и 404 "Not found" вместо безликого 400 "Bad Request", когда это уместно. Как правило 400 кодом пользуются когда нужно ответить на какую-то ошибку валидации или в случае возникновения бизнесовой ошибки, которую вы заранее можете предсказать (очень настоятельно рекомендую хотя бы дополнять код ответа еще и кодом бизнесовой ошибки в этом случае. Для валидации желательно тоже). А для всего остального лучше использовать специальные коды.