Strukturyzacja dokumentacji online dla REST API

Buduję moje pierwsze API Rest, które serializuje dane do formatów JSON i XML. Chciałbym udostępnić klientom API stronę indeksu, na której mogliby wybierać zaimplementowane punkty końcowe.

Jakie informacje muszę uwzględnić, aby mój interfejs API był najbardziej przydatny i jak powinienem go zorganizować?

To bardzo złożone pytanie wymagające prostej odpowiedzi.

Możesz przyjrzeć się istniejącym strukturom API, takim jak Swagger Specification ( OpenAPI ) oraz usługom, takim jak apiary.io i apiblueprint.org .

Oto przykład tego samego interfejsu API REST opisanego, zorganizowanego, a nawet stylizowanego na trzy różne sposoby. Może to być dobry początek, aby uczyć się na podstawie istniejących, powszechnych sposobów.

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

Myślę, że na najwyższym poziomie dokumenty REST API wymagają co najmniej następujących elementów:

• lista wszystkich punktów końcowych API (podstawowe / względne adresy URL)
• odpowiedni typ metody HTTP GET / POST / ... dla każdego punktu końcowego
• żądanie / odpowiedź typ MIME (jak kodować parametry i analizować odpowiedzi)
• przykładowe żądanie / odpowiedź, w tym nagłówki HTTP
• typ i format określony dla wszystkich parametrów, w tym w adresie URL, treści i nagłówkach
• krótki opis tekstowy i ważne uwagi
• krótki fragment kodu pokazujący użycie punktu końcowego w popularnych językach programowania w sieci

Istnieje również wiele struktur dokumentów opartych na JSON / XML, które mogą analizować definicję lub schemat interfejsu API i generować wygodny zestaw dokumentów. Ale wybór systemu generowania dokumentów zależy od projektu, języka, środowiska programistycznego i wielu innych rzeczy.