Strutturazione della documentazione in linea per un'API REST

Sto costruendo la mia prima API Rest che serializza i dati nei formati JSON e XML. Vorrei fornire una pagina di indice ai client API, dove sarebbero in grado di scegliere gli endpoint implementati.

Quali informazioni devo includere per rendere la mia API più utile e come dovrei organizzarla?

Questa è una domanda molto complessa per una risposta semplice.

Potresti voler dare un'occhiata ai framework API esistenti, come Swagger Specification ( OpenAPI ) e servizi come apiary.io e apiblueprint.org .

Inoltre, ecco un esempio della stessa API REST descritta, organizzata e persino stilizzata in tre modi diversi. Potrebbe essere un buon inizio per imparare dai metodi comuni esistenti.

• https://api.coinsecure.in/v1
• https://api.coinsecure.in/v1/originalUI
• https://api.coinsecure.in/v1/slateUI#!/Blockchain_Tools/v1_bitcoin_search_txid

Al livello più alto penso che i documenti API REST di qualità richiedano almeno quanto segue:

• un elenco di tutti i tuoi endpoint API (URL di base / relativi)
• tipo di metodo HTTP GET / POST / ... corrispondente per ogni endpoint
• richiesta / risposta tipo MIME (come codificare i parametri e analizzare le risposte)
• una richiesta / risposta di esempio, comprese le intestazioni HTTP
• tipo e formato specificato per tutti i parametri, inclusi quelli nell'URL, nel corpo e nelle intestazioni
• una breve descrizione testuale e note importanti
• un breve snippet di codice che mostra l'uso dell'endpoint nei più diffusi linguaggi di programmazione web

Inoltre ci sono molti framework di documenti basati su JSON / XML che possono analizzare la definizione o lo schema dell'API e generare un comodo set di documenti per te. Ma la scelta per un sistema di generazione di documenti dipende dal progetto, dalla lingua, dall'ambiente di sviluppo e da molte altre cose.