Структурування онлайн-документації для REST API

Я будую свій перший Rest API, який серіалізує дані у форматах JSON та XML. Я хотів би надати індексну сторінку клієнтам API, де вони могли б вибрати обрані кінцеві точки.

Яку інформацію мені потрібно включити, щоб зробити свій API найбільш корисним, і як я повинен це організувати?

Це дуже складне питання для простої відповіді.

Можливо, ви захочете поглянути на існуючі фреймворки API, такі як Специфікація Swagger ( OpenAPI ), та такі послуги, як apiary.io та apiblueprint.org .

Крім того, ось приклад того самого API REST, який описаний, організований і навіть стилізований трьома різними способами. Це може бути гарним початком для вас, щоб навчитися на існуючих загальноприйнятих способах.

• 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 або схему та сформувати для вас зручний набір документів. Але вибір системи генерації документів залежить від вашого проекту, мови, середовища розробки та багатьох інших речей.