Hej! Jako dostawca API (aktywny składnik farmaceutyczny) często pytam o schemat API. Pomyślałem więc, że poświęcę trochę czasu, aby cię rozbić w sposób, który jest łatwy do zrozumienia.
Zacznijmy od podstaw. Schemat API jest jak plan API. Jest to szczegółowy opis działania interfejsu API, jakie dane oczekuje i jakie dane zwróci. Pomyśl o tym jak o zbiorze zasad i wytycznych, które zarówno dostawca API (to ja!), Jak i konsument API (to ty lub twój zespół) muszą przestrzegać, aby zapewnić płynną i wydajną komunikację.
Dlaczego schemat API jest ważny?
Wyobraź sobie, że budujesz dom. Nie zacząłbyś po prostu rzucać cegieł bez planu, prawda? To samo dotyczy API. Schemat API stanowi jasny i spójny sposób dla programistów do zrozumienia i korzystania z API. Pomaga uniknąć nieporozumień, zmniejsza szanse na błędy i ułatwia integrację API z różnymi aplikacjami.
Załóżmy na przykład, że jesteś programistą, który chce korzystać z naszego interfejsu API, aby uzyskać dostęp do informacji oNano-karbonizowany niob, Micron Niobium Carbide, Ultra-Fine Niobium Carbide, HFC. Schemat API poinformuje dokładnie, jakie punkty końcowe są dostępne, jakie parametry musisz przejść, i w jakim formacie będzie odpowiedź. To znacznie ułatwia napisanie kodu w interakcji z interfejsem API i uzyskanie potrzebnych danych.
Co jest w schemacie API?
Schemat API zwykle zawiera następujące elementy:
1. Punkty końcowe
Są to adresy URL, które można wywołać, aby uzyskać dostęp do funkcjonalności API. Każdy punkt końcowy reprezentuje określoną operację, taką jak uzyskanie listy produktów, tworzenie nowego zamówienia lub aktualizacja informacji o użytkowniku.
2. Formaty żądania i odpowiedzi
Schemat zdefiniuje format danych, które należy wysłać w swoich żądaniach (np. JSON, XML) i format danych, które API zwróci w swoich odpowiedzi. Zapewnia to, że zarówno dostawca API, jak i konsument znajdują się na tej samej stronie, jeśli chodzi o obsługę danych.
3. Parametry
Są to wartości, które można przekazać do punktu końcowego w celu dostosowania operacji. Na przykład możesz przekazać identyfikator produktu, aby uzyskać informacje o określonym produkcie lub zakres dat w celu filtrowania listy zamówień.
4. Obsługa błędów
Schemat opisuje również, w jaki sposób interfejs API będzie obsługiwał błędy. Zdefiniuje kody błędów, które może zwrócić interfejs API i co oznacza każdy kod. Pomaga to programistom zrozumieć, co poszło nie tak, gdy wystąpi błąd i jak go naprawić.
Rodzaje schematów API
Istnieje kilka rodzajów schematów API, każdy z własnymi zaletami i przypadkami użycia. Niektóre z najczęstszych to:
Specyfikacja Openapi (OAS)
Jest to jeden z najpopularniejszych standardów dokumentowania RESTful API. Używa pliku YAML lub JSON do opisania punktów końcowych API, formatów żądań i odpowiedzi, parametrów i innych. OAS jest powszechnie obsługiwany przez narzędzia i ramy, co ułatwia generowanie dokumentacji, SDK i przypadków testowych.
Schemat GraphQL
GraphQL to język zapytania dla interfejsów API, który pozwala klientom zażądać dokładnie potrzebnych danych. Schemat GraphQL określa typy danych, które API może zwrócić, oraz operacje, które można wykonać w tych typach. Zapewnia bardziej elastyczny i wydajny sposób dostępu do danych w porównaniu z tradycyjnymi interfejsami API RESTful.
Bufory protokołu
Bufory protokołów (ProtOBUF) to format serializacji binarnej językowej opracowany przez Google. Używa pliku schematu do zdefiniowania struktury danych, które zostaną serializowane i deserializowane. Protobuf jest znany z wysokiej wydajności i małego rozmiaru wiadomości, co czyni go popularnym wyborem dla interfejsów API, które muszą obsługiwać duże ilości danych.
Jak używamy schematów API jako dostawcy API
Jako dostawca interfejsu API polegamy na schematach API, aby zapewnić, że nasze interfejsy API są łatwe w użyciu i zintegrowane. Używamy specyfikacji OpenAPI do udokumentowania naszych interfejsów API, która pozwala nam zapewnić naszym klientom jasną i szczegółową dokumentację. Niniejsza dokumentacja zawiera informacje o punktach końcowych, formatach żądań i odpowiedzi, parametrach i obsługi błędów.
Używamy również schematów API do potwierdzenia żądań, które otrzymujemy od naszych klientów. Sprawdzając przychodzące żądania w stosunku do schematu, możemy upewnić się, że dane są we właściwym formacie i że wszystkie wymagane parametry są obecne. Pomaga to zapobiec błędom i zapewnia, że nasze interfejsy API są niezawodne i bezpieczne.
Ponadto używamy schematów API do generowania SDK i przypadków testowych. Korzystając z narzędzi obsługujących specyfikację OpenAPI, możemy automatycznie generować kod w różnych językach programowania, co ułatwia naszym klientom integrację naszych interfejsów API z ich aplikacjami. Używamy również schematu do generowania przypadków testowych, co pomaga nam upewnić się, że nasze interfejsy API działają poprawnie i że spełniają wymagania naszych klientów.
Przykłady prawdziwego świata
Rzućmy okiem na niektóre rzeczywiste przykłady zastosowania schematów API.
Przykład 1: Korzystanie z naszego interfejsu API, aby uzyskać informacjeWysokiej jakości thixanthen-9-one CAS: 492-22-8
Załóżmy, że jesteś badaczem, który chce uzyskać informacje o określonym związku chemicznym. Możesz użyć naszego interfejsu API, aby uzyskać dostęp do danych, takich jak właściwości związku, metody syntezy i informacje o bezpieczeństwie. Schemat API poinformuje dokładnie, jaki punkt końcowy nazywa, jakie parametry przejść (np. Numer CAS) i w jakim formacie będzie odpowiedź.
Oto przykład prośby do naszego interfejsu API za pomocą Curl:
curl -x zdobądź „https://api.oursite.com/compounds/492-22-8„ -h ”Akceptuj: Application/Json”Odpowiedź może wyglądać mniej więcej tak:
{„Nazwa”: „thioxanthen-9 -e”, „cas_number”: „492-22-8”, „molecular_weight”: 212.26, „Właściwości”: {„MEFTING_POINT”: „85-87 ° C”, „Boiling_point”: „365.7 ° C at 760 MMHG”, „Synysis_methods”: „”: [BOILIZA ”,„ Boiling_Point ”:„ 365.7 ° C 1: React x z y w obecności Z ... ”,„ Metoda 2: Użyj następujących warunków reakcji ... ”]}Przykład 2: Tworzenie nowego zamówienia dlaCAS nr 455943-61-0 Duża podaż
Jeśli jesteś firmą farmaceutyczną, która chce złożyć zamówienie na dużą dostawę konkretnego interfejsu API, możesz użyć naszego interfejsu API do stworzenia nowego zamówienia. Schemat API zdefiniuje punkt końcowy do utworzenia zamówienia, format żądania (np. Szczegóły zamówienia, ilość i adres dostawy) oraz format odpowiedzi (np. Identyfikator zamówienia i komunikat potwierdzający).
Oto przykład prośby do naszego interfejsu API za pomocą Pythona:
Importuj żądania url = "https://api.oursite.com/orders" data = {"product_id": "455943-61-0", "ilość": 1000, "dostawa_address": "123 Main st, Anytown, USA"} nagłówki nagłówki = nagłówki) print (response.json ())Odpowiedź może wyglądać mniej więcej tak:
{„Order_id”: „123456”, „Message”: „Zamówienie utworzone pomyślnie. Twoje zamówienie zostanie przetworzone w ciągu 24 godzin”. }Wniosek
Podsumowując, schemat API jest kluczową częścią każdego API. Zapewnia dla programistów jasny i spójny sposób zrozumienia i korzystania z interfejsu API, zmniejsza szanse na błędy i ułatwia integrację interfejsu API z różnymi aplikacjami. Jako dostawca API polegamy na schematach API, aby zapewnić, że nasze interfejsy API są łatwe w użyciu, niezawodne i bezpieczne.
Jeśli chcesz korzystać z naszych interfejsów API w celu uzyskania dostępu do informacji o naszych produktach lub do składania zamówień, chcielibyśmy usłyszeć od Ciebie. Niezależnie od tego, czy jesteś badaczem, firmą farmaceutyczną, czy programistą, nasze interfejsy API mogą dostarczyć potrzebnych danych i funkcjonalności. Nie wahaj się więc skontaktować się z nami, aby omówić Twoje wymagania i rozpocząć proces zamówień. Jesteśmy tutaj, aby pomóc Ci w pełni wykorzystać nasze interfejsy API i zapewnić, że twoje doświadczenie z nami jest pozytywne.
Odniesienia
- Fielding, RT (2000). Style architektoniczne i projekt architektur oprogramowania opartych na sieci. University of California, Irvine.
- Khare, R., i Frytyk, H. (1997). Protokół transferu hipertekstu - HTTP/1.1. RFC 2068.
- Lindley, S. i Miller, B. (2015). GraphQL: język zapytania o dane. Facebook.
- Varda, A. (2008). Bufory protokołu: format wymiany danych Google. Blog Google Open Source.
