Projektowanie API

Od wymagań do API

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

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

Na przykład, jeśli jesteś firmą dostarczającą jedzenie, możesz chcieć zbudować 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ą oni musieli manipulować danymi o restauracjach i wykonywać zapytania wyszukiwania na danych, z pewnymi możliwościami filtrowania i sortowania.

Inny przykład: jeśli jesteś firmą oferującą kalendarz w modelu SaaS, możesz chcieć zbudować API, aby inni programiści front-end na świecie mogli tworzyć nowe aplikacje mobilne i internetowe w oparciu o Twój system kalendarza.

Myślenie o konsumentach Twojego API to pierwszy krok w kierunku zapewnienia im dobrego doświadczenia programistycznego. Pomoże to Twojemu API wyróżnić się i zwiększyć poziom zaangażowania.

Elementy tworzące API

Podczas projektowania API wykorzystuje się cztery kluczowe koncepcje:

• Zasób to element, z którym Twoi konsumenci będą wchodzić w interakcję za pośrednictwem Twojego API. Zasoby są jednoznacznie identyfikowane przez ścieżkę, która w połączeniu z punktem końcowym API zapewnia unikalny adres zasobu w sieci. Na przykład Calendars to nazwa zasobu, który odpowiada 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 używa metody GET na zasobie Calendars.
• Typ danych to opis rzeczywistych danych wymienianych w sieci. Na przykład Calendar to nazwa typu danych, który opisze wszystkie właściwości kalendarza, takie jak jego nazwa, właściciel i odniesienie do należących do niego wydarzeń. Operacja List all Calendars zwraca listę typów danych Calendar.
• Komponent to element, który można ponownie wykorzystać 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 tworzą 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, i hosta, takiego jak www.calendar-api.com.
• Blok Tekst może być użyty do swobodnego wprowadzania dowolnego tekstu (w tym markdown), który można umieścić w dowolnym miejscu w projekcie API. Używaj bloków tekstowych do wyjaśniania tematów przekrojowych, takich jak uwierzytelnianie i obsługa błędów.
• Sekcja służy do sensownego grupowania zasobów i typów danych. Użyj ich, aby projekt 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 API Designer będziesz mógł tworzyć te elementy z menu Utwórz nowe w prawym górnym rogu.

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