Strukturyzacja dokumentacji online dla REST API

85

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ć?

api rest indexing aumanets
źródło

Odpowiedzi:

6

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.

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.

Igor Kroitor
źródło