10 ważnych składników dokumentacji API

Coraz więcej organizacji wykorzystuje moc interfejsów API do optymalizacji swojej działalności. Interfejsy API stały się sposobem na odblokowanie wartości i zapewnienie dodatkowej usługi.

Pomimo ich ogólnej popularności, nie każde API odnosi sukces. Przyjęcie i użycie interfejsu API w dużej mierze decyduje o jego sukcesie. Aby zwiększyć adopcję, Twój interfejs API musi być łatwy do znalezienia i użycia.

Najlepszym sposobem na to jest szczegółowe udokumentowanie interfejsu API. Obejmuje to wyszczególnienie krytycznych komponentów, aby ułatwić ich zrozumienie. Dowiedz się, jakie komponenty należy uwzględnić w dokumentacji interfejsu API.

Co to jest dokumentacja API?

Dokumentacja interfejsu API to treść techniczna, która szczegółowo opisuje interfejs API. Jest to instrukcja zawierająca wszystkie informacje potrzebne do pracy z API. Dokument obejmuje cykl życia API oraz instrukcje dotyczące integracji i korzystania z jego komponentów.

Dokumentacja interfejsu API obejmuje opisy zasobów, punkty końcowe, metody, żądania i przykłady odpowiedzi. Może również zawierać praktyczne przewodniki i samouczki pokazujące użytkownikom, jak go zintegrować. Eksploracja każdej sekcji daje użytkownikom solidne zrozumienie integracji i korzystania z interfejsu API.

Edytory, takie jak Dokumenty Google, były kiedyś powszechnie używane do profesjonalnej dokumentacji API. Obecnie dostępne są bardziej zaawansowane narzędzia, takie jak Document 360, Confluence i GitHub Pages. Te narzędzia pomagają integrować tekst i kod w celu ułatwienia przepływu pracy.

1. Omówienie i cel interfejsu API

Pierwszym krokiem w dokumentowaniu interfejsu API jest poinformowanie użytkowników, o co w nim chodzi. Dołącz informacje o rodzaju udostępnianych zasobów. Interfejsy API zwykle zwracają różne zasoby, więc użytkownik może zażądać tego, czego potrzebuje.

Opis jest krótki, zwykle od jednego do trzech zdań opisujących zasób. Opisz dostępny zasób, punkty końcowe i metody dołączone do każdego punktu końcowego. Jako programista interfejsu API najlepiej opisz jego komponenty, funkcjonalność i przypadek użycia.

Oto przykład opisu API Airbnb:

2. Metody uwierzytelniania i autoryzacji

Interfejsy API obsługują tysiące żądań i ogromne ilości danych. Uwierzytelnianie to jeden ze sposobów zapewnienia bezpieczeństwa danych interfejsu API i użytkowników przed hakerami. Uwierzytelnianie API weryfikuje tożsamość użytkownika i daje im dostęp do zasobów.

Istnieje kilka sposobów zapewnienia bezpieczeństwo punktów końcowych. Większość interfejsów API używa klucza API. Jest to ciąg znaków, który użytkownik może wygenerować ze strony internetowej i użyć do uwierzytelnienia.

Dokumentacja interfejsu API powinna wskazywać użytkownikom, jak uwierzytelniać i autoryzować swoją tożsamość. Na poniższym diagramie przedstawiono informacje uwierzytelniające API Twittera.

3. Punkty końcowe, wzorce URI i metody HTTP

W tej sekcji zademonstruj, jak uzyskać dostęp do zasobu. Punkty końcowe pokazują tylko koniec ścieżki, stąd ich nazwa. Pokazują dostęp do zasobu i metody HTTP punkt końcowy współdziała z, a mianowicie GET, POST lub DELETE.

Jeden zasób prawdopodobnie ma różne punkty końcowe. Każdy inną drogą i metodą. Punkty końcowe zwykle mają krótkie opisy ich przeznaczenia i wzorzec adresu URL.

Poniższy przykładowy kod przedstawia punkt końcowy użytkownika GET na Instagramie.

DOSTAĆ / mnie? pola={pola}&access_token={token-dostępu}

4. Formaty żądań i odpowiedzi

Musisz udokumentować formaty żądań i odpowiedzi, aby użytkownik wiedział, czego się spodziewać. Żądanie to adres URL od klienta z prośbą o zasób, a odpowiedź to informacja zwrotna z serwera.

Poniżej przedstawiono przykładowe żądanie, które można wysłać do interfejsu API LinkedIn.

DOSTAWAĆ https://api.linkedin.com/v2/{service}/1234

A oto przykładowa odpowiedź, którą może zwrócić:

{
 "identyfikator": 1234,
 "powiązany podmiot": "urn: li: powiązany podmiot: 6789"
}

5. Parametry i nagłówki

Powinieneś także udokumentować parametry swoich punktów końcowych, czyli opcje, które możesz im przekazać. Parametrami mogą być identyfikatory lub liczby określające ilość lub typ danych zwracanych w odpowiedzi.

Istnieją różne typy parametrów, w tym parametry nagłówka, ścieżki i ciągu zapytania. Punkty końcowe mogą zawierać różne typy parametrów.

Możesz dołączyć niektóre parametry jako nagłówki żądań HTTP. Zwykle służą one do celów uwierzytelniania, takich jak klucz API. Oto przykład nagłówka z kluczami API:

nagłówki: {
 „X-RapidAPI-Key”: „fd40ada866msh4d8b69e4aa2dd19p12e47fjsn7efdcbc75635”,
 „X-RapidAPI-Host”: „wft-geo-db.p.rapidapi.com”
}

Parametry ścieżki umieszczasz w treści punktu końcowego bezpośrednio w adresie URL. Pokazują użytkownikowi, jak i gdzie umieścić parametry oraz jak pojawi się odpowiedź. Słowa w nawiasach klamrowych to parametry.

Możesz także użyć dwukropków lub innej składni do reprezentowania parametrów ścieżki.

/service/myresource/user/{user}/bicycles/{bicycleId}

W przypadku parametrów zapytania należy umieścić znak zapytania (?) przed zapytaniem w punkcie końcowym. Oddziel każdy parametr znakiem ampersand (&). Microsoft ma dobrą dokumentację dotyczącą Graph API.

6. Kody błędów i obsługa błędów

Czasami żądania HTTP kończą się niepowodzeniem, co może wprowadzić użytkownika w błąd. Dołącz oczekiwane kody błędów do dokumentacji, aby pomóc użytkownikom zrozumieć błędy.

LinkedIn udostępnia standardowe kody błędów HTTP do obsługi błędów:

7. Przykładowe fragmenty kodu

Fragmenty kodu to podstawowe części Twojej dokumentacji. Pokazują użytkownikom, jak zintegrować API w różnych językach i formatach. Dołącz do dokumentacji, jak zainstalować i zintegrować SDK (zestawy programistyczne) w różnych językach.

RapidAPI ma dobre przykłady fragmentów kodu dla programistów:

9. Wersjonowanie API i dzienniki zmian

Wersjonowanie API jest istotną częścią Projekt interfejsu API. Zapewnia nieprzerwane dostarczanie usług użytkownikom. Wersjonowanie może rozszerzyć interfejs API o nowe wersje bez wpływu na aplikacje klienckie.

Użytkownicy mogą nadal korzystać ze starszych wersji lub z czasem przejść na bardziej zaawansowane. Jeśli w dziennikach pojawią się nowe zmiany, dołącz je do dokumentacji, aby użytkownicy byli o tym poinformowani.

Microsoft Graph API ma dobrze udokumentowane dzienniki zmian:

Na koniec umieść w dokumentacji ważne kontakty w celu uzyskania wsparcia i opinii. Zapewniają one użytkownikom kontakt z raportami o błędach i informacjami o tym, jak ulepszyć interfejs API.

Wartość dokumentacji API

Jeśli tworzysz API dla wartości komercyjnej, konsumpcja decyduje o jego sukcesie. Aby użytkownicy mogli korzystać z Twojego interfejsu API, muszą go zrozumieć.

Dokumentacja ożywia interfejs API. Wyjaśnia szczegółowo komponenty w prostym języku, który sprzedaje użytkownikom ich wartość i zastosowanie. Użytkownicy chętnie skorzystają z Twojego interfejsu API, jeśli będą mieli świetne doświadczenie programistyczne.

Dobra dokumentacja pomaga również uprościć konserwację i skalowanie API. Zespoły pracujące z interfejsem API mogą korzystać z dokumentacji do zarządzania nim.