Я создаю свой первый API-интерфейс Rest, который преобразует данные в формат JSON и XML. Я хотел бы предоставить индексную страницу для клиентов API, где они смогут выбирать реализованные конечные точки.
Какую информацию мне нужно включить, чтобы сделать мой API наиболее полезным и как его организовать?
Это очень сложный вопрос для простого ответа.
Вы можете взглянуть на существующие рамки API, например Swagger Спецификация (OpenAPI) и сервисы, такие как apiary.io и apiblueprint.org.
Кроме того, здесь приведен пример одного и того же REST API, организованного и даже стилизованного тремя способами. Это может быть хорошим началом для вас, чтобы учиться на существующих общих путях.
На самом верхнем уровне я считаю, что для качественных документов REST API требуется, по крайней мере, следующее:
Также существует множество основанных на JSON/XML-инфраструктур документов, которые могут анализировать ваше определение или схему API и создавать для вас удобный набор документов. Но выбор для системы генерации doc зависит от вашего проекта, языка, среды разработки и многих других.