⚡ Kotobotov ⚡

есть такой подход: посмотреть на сколько пересекаются сущности с которыми приходится работать, и специфичная для работы терминология - мне кажется что тут полное пересечение до степени смешения - поэтому я бы делал как один сервис.

да нормальный вариант с ПОСТ запросом, дополнительно замечу что все же используют специфические типы запросов -> POST для создания, для удаления Delete, для обновления небольшой части данных PUT (Post для полного создания/обновления), ну и GET для запроса данных, есть еще методы но для большинства этих методов полностью хватает.

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

Первый пример ориентируется на упрощение НО тогда если у тебя существует только ОДНО поле для категории (айди), тогда ты просто пишешь -> {"category": 1} (без айди в имени)
тоесть если и упрощать, так все упрощать, включая названия.
Но скорее всего у категории существует не только идентификатор но также еще и название, что не упростить в одном поле, значит все равно нужно выводить как во втором варианте обьект category, с двумя полями id, и name
просто же выводить обьект с одним вложенным полем - это ненужная избыточность, такое лучше заменить на первый вариант.
-------
по поводу: POST в одном формате, а при GET отдают в другом.
за такое просто в морду бить надо, тк это подразумевает разработчику необходимость создания 2х разных представлений для структур данных одного и тогоже обьекта.

heroku.com иногда использую чтоб что-то быстро залить и показать как работает.
заливать код можно одной строчкой через "гит пуш", сервис автоматически подбирает по коду какое окружение нужно создать чтоб этот код работал, удобно и есть бесплатный "хобби" тариф

данные о пользователе передаются или в виде параметра в ссылке, либо в виде заголовка запроса
поэтому можно GET, POST /course/:courseUuid

П. С.
ни что не мешает лесону иметь и ГЕТ /courses/:courseUuid/:lessonUuid
и GET /lesson/:lessonUuid
типовой подход иметь унифицированный апи, с одинаковыми ПОСТ и ГЕТ (и добавочные запросы с низкой иерархией типа /lesson/:lessonUuid)

Сомнительное утверждение, возможно что-то напутали с разметкой текста в переводе.
Если запрос идемпотентный - то его можно кэшировать, ни пут ни делит кэшировать нельзя.
опять зашел на вики глянул, там указанно что например ПУТ возвращает разные статусы если есть изменяемый контент или его нет при отправке.
В целом ничего не мешает вам реализовать одинаковые ответы. Строгих стандартов нет, есть только общие рекомендации. Мне например нравиться вариант для ДЕЛЕТ с одинаковыми ответами.
Тогда отзывчивость сервера будет выше, раз тебе не нужно дожидаться окончания задачи, для отправки статуса (тоесть можно отправить задачу по удалению на сервер асинхронно и вернуть не дожидаясь результата статус 200).

привет брат поразуму, всегда также делаю и считаю глупостей вначале передавать код 200 (все оке), а потом еще в ответе писать {статус: "все оке"}

с другой стороны полно недалеких разрабов, которые не знают как работать с заголовками - и если у тебя какой-то массовый сервис для дебилов, то возможно им нужно дублировать и в теле инфомацию, но я не понимаю как ты для них продублируешь инфу в ответе если например сервак упал, или там 404 выдал.
хотя я за чистоту апи, чтоб служебной информации в ответе не было, вся служебная информация чтоб в заголовках ппередавалась.
С другой стороны АПИ должно быть понятным и очевидным без документации, поэтому лучше передавать не просто массив, а именнованный данные.
Пример:
запрос гет хттп://юзер/1
ответ {имя: "вася", возраст: 18}, а не {["вася", "18"]}

нет какой-то жесткой спецификации.
оба варианта подходят, и несколько вариантов тоже подходят)

на текущий момент все сами придумывают свой "язык апи" для описания своих сервисов, тк нет определённости какой именно функционал и как вы хотите показать через апи.

очень легко мыслить токенами, как сессией, но токен это не сессия, не стоит путать.
Токены используют как раз для того чтоб отойти от классической схемы с сессиями/паролями.
по порядку:
1) смотрите у вас есть сервис, состоит например из 10 серверов, которые отвечают за разные части функционала, поскольку функционал коммерческий вам нужно проверять каждый запрос от пользователя есть ли у него права для этого запроса.
вы вынуждены сделать единый сервер валидации, и с каждого своего сервера, для каждого запроса, запрашивать на сервере валидации проверку пользователя и его прав.
в такой ситуации сервер валидации для вашего сервиса становиться бутылочным горлышком, и мешает горизонтальной масштабируемости.
и абсолютно без разницы валидируете вы пользователя по паролю, айпи, или токену, сессии, схема одна и таже, производительность тоже одна и таже (именно поэтому нет никакого смысла менять сверку пользователя вместо пароля на сверку по айпи, или токену, или сессию, тем более понятно почему использования айпи в этой схеме просто глупая идея).

поэтому есть задача отойти от этой схемы, для возможности простого горизонтального масштабирования, для этого вы берёте информацию о пользователе (например его айди, права, и тд) и зашифровываете эти данные, и передаёте пользователю в виде токена.
2) На каждом вашем сервере есть алгоритм быстрой расшифровки, который на лету проверяет токены, и из него получает нужную информацию, о правах и айди пользователя (валидирует пользователя, без бутылочного горлышка), сами токены временные, в них также вшивают информацию о времени его действия, обычно в районе пары часов/суток, после чего вы перегенерируете токен заново (ключ для перегенерации и получения нового токена также вшиваете в токен, осуществляя непрерывность процесса перегенерации токенов).
3. Что делать если пользователь поменял пароль?
ничего - токен даёт пользователю право на вход, и не имеет значения какой у пользователя пароль.

OAuth2 слишком простой, не делают для него какой-то особой поддержки)

дык чего придумывать -> прийди к этим господам в контору, и напросись стажёром, на их проект.