Konstrukcja API

Przejście od wymagań do API

Podobnie jak większość technologii, API jest rozwiązaniem problemu. Aby zaprojektować odpowiednie API, musisz upewnić się, że rozwiązywany problem jest jasno zdefiniowany, odpowiadając na następujące pytania:

• Kim są docelowi odbiorcy tego API?
• Jakiego rodzaju informacjami konsumenci będą manipulować za pośrednictwem API?
• Jakie działania będą wykonywać konsumenci na API?

Na przykład, jeśli prowadzisz firmę zajmującą się dostawą jedzenia, możesz chcieć utworzyć API dla swojej sieci partnerskiej, które umożliwi im przeglądanie i przeszukiwanie bazy danych restauracji, dla których świadczysz usługi dostawy.

W tym przykładzie Twoje API jest skierowane do partnerów Twojej firmy. Będą musieli manipulować danymi dotyczącymi restauracji oraz wykonywać zapytania wyszukiwania na tych danych, z określonymi możliwościami filtrowania i sortowania.

Inny przykład: jeśli jesteś firmą SaaS oferującą kalendarz, możesz chcieć zbudować API, aby inni programiści front-end na świecie mogli tworzyć nowe aplikacje mobilne i internetowe oparte na Twoim systemie kalendarza.

Myślenie o konsumentach Twojego API to pierwszy krok w kierunku zapewnienia im dobrych doświadczeń programistycznych. Pomoże to wyróżnić Twoje API i zwiększyć poziom zaangażowania.

Elementy składające się na API

Istnieją cztery kluczowe koncepcje wykorzystywane podczas projektowania API:

• Zasób to element, z którym Twoi konsumenci będą wchodzić w interakcję za pośrednictwem Twojego API. Zasoby są jednoznacznie identyfikowane za pomocą ścieżki, która w połączeniu z punktem końcowym API zapewnia unikatowy adres zasobu w sieci. Na przykład Calendars to nazwa zasobu odpowiadającego liście kalendarzy, a jego ścieżka to /calendars.
• Operacja to działanie, które można wykonać na Twoich zasobach. Najczęstsze operacje to GET (odczyt), POST (tworzenie), PUT (aktualizacja) i DELETE. Na przykład List all Calendars to nazwa operacji, która wykorzystuje metodę GET na zasobie Calendars.
• Typ danych to opis rzeczywistych danych wymienianych przez sieć. Na przykład Calendar to nazwa typu danych, który opisuje wszystkie właściwości kalendarza, takie jak jego nazwa, właściciel oraz odwołanie do należących do niego wydarzeń. Operacja List all Calendars zwraca listę typów danych Calendar.
• Komponent to element, który może być wielokrotnie wykorzystywany w całej definicji API. Na przykład jeśli musisz użyć tego samego parametru zapytania w kilku operacjach, możesz utworzyć go jako komponent i odwoływać się do niego w tylu operacjach, ile potrzeba.

Istnieją inne przydatne elementy, które składają się na API:

• Punkt końcowy to główny punkt wejścia dla Twojego API w sieci. Punkt końcowy składa się ze schematu, takiego jak HTTPS, oraz hosta, takiego jak www.calendar-api.com.
• Blok Tekst może być używany do swobodnego wprowadzania dowolnego tekstu (w tym Markdown), który można umieścić w dowolnym miejscu projektu API. Używaj bloków tekstu do wyjaśniania zagadnień przekrojowych, takich jak uwierzytelnianie i obsługa błędów.
• Sekcja służy do logicznego grupowania zasobów i typów danych. Użyj ich, aby projekt Twojego API był bardziej przejrzysty i przyjazny dla programistów. Możesz przeciągnąć i upuścić elementy do sekcji w lewym panelu, a także zmieniać kolejność sekcji między sobą.

W Kontraktach API będzie można utworzyć te elementy z menu Utwórz nowy w prawym górnym rogu.

Adresy URL serwera są tworzone na ekranie informacji ogólnych. Adres URL serwera może mieć stan Opublikowany lub Nieopublikowany. Jeśli jest opublikowany, pojawia się w Live Documentation.