Я нашел документацию Netflix очень хорошей и поможет вам понять, что входит в разработку API. API не идеален, но я думаю, что это хорошая комбинация практического и продуманного.
Идея самодокументирующегося REST API заключается в том, что можно получить единую точку входа в систему и иметь возможность обнаружить все функциональные возможности, доступные через возвращенные документы, в сочетании с пониманием стандартного использования глаголов REST (GET, ПОСТАВИТЬ, УДАЛИТЬ). Таким образом, если вы извлекаете список сотрудников из системы RESTful, отдельные записи будут указывать URL-адрес этой записи, а поле работодателя будет указывать URL-адрес работодателя. Выполните поиск по HATEOAS для получения более подробной информации. Но вы можете позвонить «/ employee» и получить:
<employees>
<employee id=132 name=bob url="/employee/132" employer="/employer/176"/>
<employee id=179 name=carl url="/employee/132" employer="/employer/122"/>
</employees>
Вы можете просмотреть полную запись о сотруднике в / employee / 132 и просмотреть запись о своем работодателе в / Employer / 176. По договоренности, если у вас есть разрешение, вы можете обновить bob сотрудника, используя PUT для / employee / 132, или создать нового сотрудника с POST для / employee. Принятые типы контента также могут запрашиваться через интерфейс (я думаю, с использованием HEAD).