Przewodnik po API do EasyCargo (cz.2)

Jak wspomnieliśmy w pierwszej części artykułu dziś “podejdziemy” API do EasyCargo bardziej od strony praktycznej. Wykorzystamy do tego naszego klienta API. Działanie API przetestujemy również w oparciu o narzędzie online ReqBin. Umożliwia ono komunikację z serwerem WWW, dzięki czemu możemy pobierać interesujące nas dane z programu do planowania załadunku ciężarówek i kontenerów EasyCargo. Testowanie to jedno, ale w rzeczywistości być może używałbyś wtyczki Java do swojej aplikacji lub wywołań Javascript z SAP. Więcej o tym, platformie Make oraz innych przypadkach realnego użycia API w kolejnym wpisie z tej serii.

Zobacz, jak wygląda powyższe żądanie w narzędziu ReqBin

Powyższe zdjęcie przedstawia naszego klienta API do EasyCargo. Aby móc wysyłać jakiekolwiek żądania API do serwera WWW, to w pierwszej kolejności klient musi zostać autoryzowany. Startowym żądaniem jest więc POST http://go.easycargo3d.com/api/v1/authentication z nazwą użytkownika i kluczem API w zawartości. Od serwera w odpowiedzi otrzymasz token uwierzytelniający (ang. authentication token). Każde kolejne (chyba, że zaznaczono inaczej) żądanie interfejsu API należy uwierzytelnić, dodając w jego nagłówku uzyskany token. Warto tutaj zaznaczyć, że wszystkie wykonane żądania API realizowane są w imieniu właściciela tokenu. Żądania i odpowiedzi muszą być tworzone w formacie JSON lub XML.

Jak już zostaliśmy uwierzytelnieni, to przejdźmy wreszcie do ciekawszej zabawy z API. Załóżmy, że użytkownik X ma zapisane na swoim koncie poniższe załadunki.

Przećwiczymy na nich żądania API, gdyż ładunki to chyba najważniejsza część EasyCargo. Pozostałe żądania dotyczące, np. zarządzania użytkownikami są formułowane w analogiczny sposób, więc wierzymy, że każdy czytelnik tego artykułu poradzi sobie z tworzeniem innych zapytań. W dokumentacji API do EasyCargo każda metoda interfejsu programistycznego jest opisana i wytłumaczona (dostępna tylko po angielsku).

W razie wątpliwości skontaktuj się z nami poprzez adres e-mail wsparcie@easycargo3d.com lub używając formularza kontaktowego.

Żądania API dotyczące załadunków

Jak informuje nas dokumentacja API, za pomocą odpowiednio sformułowanych żądań jesteśmy w stanie uzyskać od serwera listę wszystkich załadunków, jak i dane o konkretnym ładunku z konta EasyCargo. Możemy nawet utworzyć lub usunąć załadunek z konta.

Pozyskanie listy wszystkich załadunków

Zobacz, jak wygląda powyższe żądanie w narzędziu ReqBin

Pozyskanie danych o konkretnym ładunku

Zobacz, jak wygląda powyższe żądanie w narzędziu ReqBin

Tworzenie załadunku

Zobacz, jak wygląda powyższe żądanie w narzędziu ReqBin

Jak możesz zauważyć, załadunek został pomyślnie zapisany na koncie EasyCargo.

Ładunek utworzony za pomocą metody API możesz zwyczajnie otworzyć w aplikacji.

Usuwanie ładunku

Zobacz, jak wygląda powyższe żądanie w narzędziu ReqBin

Załadunek został poprawnie usunięty z konta EasyCargo dzięki odpowiedniemu żądaniu.

Jeszcze kilka słów o API

• Możesz wykonać maksymalnie 60 żądań API w trakcie jednej godziny.
• Błędy interfejsu programistycznego są zgłaszane jako typowe kody odpowiedzi HTTP. W większości przypadków ciało odpowiedzi zawiera wiadomość, co poszło nie tak.
• Kalkulacje planu załadunku nie mogą być wykonywane za pośrednictwem API.
• Twój klient API musi obsługiwać dostęp oraz modyfikację nagłówków żądania, jak i odpowiedzi.
• Niektóre metody API wspierają używanie opcjonalnych parametrów, np. from. Znaczenia każdego z nich dowiesz się naturalnie z dokumentacji. Parametry te możesz zastosować m.in. w przypadku żądania dotyczącego uzyskania listy wszystkich ładunków. Wystarczy, że dopiszesz je do adresu zasobu po znaku ?, rozdzielone znakiem & w postaci nazwa=wartość, np. http://go.easycargo3d.com/api/v1/shipments?from=2020-01-02&offset=0&limit=100.

Przechodząc do podsumowania tego artykułu, API to bardzo użyteczna usługa. Mamy nadzieję, że ten praktyczny opis wyjaśnił Ci bardziej, jak działa interfejs programistyczny. Dzisiejszy artykuł jest drugim z serii o API do EasyCargo, więc jeśli nie widziałeś jeszcze pierwszej części, to znajdziesz ją tutaj. Interfejs programistyczny otwiera furtkę możliwości. W kolejnym wpisie dowiesz się, jakie możesz mieć korzyści z używania naszego API oraz poznasz realne przypadki jego użycia.