Ответ 1
Это очень сложный вопрос для простого ответа.
Вы можете взглянуть на существующие рамки API, например Swagger Спецификация (OpenAPI) и сервисы, такие как apiary.io и apiblueprint.org.
Кроме того, здесь приведен пример одного и того же REST API, организованного и даже стилизованного тремя способами. Это может быть хорошим началом для вас, чтобы учиться на существующих общих путях.
- https://api.coinsecure.in/v1
- https://api.coinsecure.in/v1/originalUI
- https://api.coinsecure.in/v1/slateUI#!/Blockchain_Tools/v1_bitcoin_search_txid
На самом верхнем уровне я считаю, что для качественных документов REST API требуется, по крайней мере, следующее:
- список всех ваших конечных точек API (базовые/относительные URL-адреса)
- соответствующий тип метода HTTP GET/POST/... для каждой конечной точки
- запрос/ответ MIME-тип (как кодировать параметры и ответы на парсы)
- пример запроса/ответа, включая заголовки HTTP
- тип и формат, указанные для всех параметров, в том числе в URL, теге и заголовках
- краткое текстовое описание и важные примечания
- короткий фрагмент кода, показывающий использование конечной точки в популярных языках веб-программирования.
Также существует множество основанных на JSON/XML-инфраструктур документов, которые могут анализировать ваше определение или схему API и создавать для вас удобный набор документов. Но выбор для системы генерации doc зависит от вашего проекта, языка, среды разработки и многих других.