Nexar API — wyjaśnienie: czym jest, jak działa i co zmienia dla osób, które z niego korzystają

Najpierw: czym jest API

API to skrót od application programming interface, czyli interfejsu programowania aplikacji. Człowiek korzysta ze strony internetowej, klikając i czytając. Program nie może klikać, więc potrzebuje „okienka serwisowego”, przez które zada precyzyjne pytanie i otrzyma precyzyjną odpowiedź w zrozumiałym dla siebie formacie. Tym okienkiem jest właśnie API. Octopart to strona internetowa, na której nasi użytkownicy mogą wyszukać komponent elektroniczny i obejrzeć go z każdej strony. Taki widok obejmuje m.in. informacje o tym, kto ma komponent na stanie, ile on kosztuje, jaki jest jego status cyklu życia, jakie ma atrybuty techniczne i nie tylko. Można nawet wyszukać komponent, aby sprawdzić, które inne komponenty są do niego podobne. API Nexar dostarcza te same informacje bezpośrednio do systemów biznesowych używanych w Twojej firmie.

Korzyści z używania API Nexar

• Integracja z własnymi narzędziami: Możesz osadzić aktualne dane z API Nexar bezpośrednio w systemach wewnętrznych, takich jak niestandardowy system zarządzania zamówieniami zakupu lub system zarządzania cyklem życia produktu.
• Więcej niż dane o dostawach: Oprócz informacji o zaopatrzeniu API Nexar pobiera także dane projektowe z Twoich przestrzeni roboczych Altium 365, dzięki czemu jedna integracja może połączyć dane zakupowe i projektowe.
• Spójność między zespołami: Każdy, kto używa tego samego zapytania, otrzymuje te same wartości: tę samą cenę, ten sam poziom zapasów i te same jednostki z tego samego momentu w czasie. Dzięki temu liczby pozostają porównywalne między użytkownikami, raportami i w czasie.
• Automatyzacja na dużą skalę: API Nexar umożliwia programowe odpytywanie do 100 części jednocześnie i wykonywanie do 300 zapytań na minutę (czyli potencjalnie analizę 30 000 części w ciągu jednej minuty!)

API Nexar

API Nexar składa się przede wszystkim z: 

• Danych o dostawach — są to informacje o częściach z Octopart: warstwa zakupowa API zapewnia dostęp do ponad 95 mln części, wraz z informacjami o stanach magazynowych, cenach, statusie cyklu życia, czasie realizacji, kartach katalogowych, atrybutach technicznych, modelach CAD i sugestiach podobnych części, pochodzącymi od dystrybutorów elektroniki i aktualizowanymi codziennie. 

• Danych projektowych — przeznaczonych dla klientów Altium, obejmujących zawartość Twoich przestrzeni roboczych projektowych, od projektów po szczegóły komponentów. Publicznie przydatny jest tutaj model danych Nexar: Nexar Voyager. W modelu danych każda operacja ma prefiks wskazujący, czego dotyczy: sup dla danych o dostawach, des dla danych projektowych oraz adm dla administracji kontem.

Przykład 1: opisujesz odpowiedź, którą chcesz otrzymać

Nexar używa GraphQL, czyli języka zapytań dla API. W innych infrastrukturach API zwykle żąda się stałego bloku danych, odbiera go w całości, a następnie pisze kod odrzucający to, czego nie potrzebujesz. W GraphQL zapisujesz kształt odpowiedzi, a wraca dokładnie taki kształt. Oto udokumentowana forma wyszukiwania po MPN (manufacturer part number — numer części producenta):

query MpnSearch { 

  supSearchMpn { 

    results { part { id  name  mpn } } 

  } 

} 

Czytane na głos: wykonaj wyszukiwanie po numerach części producenta, powiedz mi, ile było trafień, a dla każdego wyniku podaj identyfikator części, nazwę i MPN. Nic więcej nie zostanie zwrócone. Poprosisz o więcej — dostaniesz więcej. W prezentacji Altium na żywo wyszukanie mikrokontrolera RA0E2 z rodziny Renesas RA zwróciło odpowiednią część; dodanie specyfikacji technicznych potwierdziło, że była oznaczona jako zgodna z RoHS (restriction of hazardous substances — ograniczenie stosowania substancji niebezpiecznych); dodanie karty katalogowej zwróciło link do pliku, jego nazwę i datę utworzenia, ponieważ Octopart ocenia dostępne karty katalogowe i może zwrócić najlepszą z nich. Nic z tego nie zostało dostarczone, dopóki nie zostało o to poproszone.

Przykład 2: wiele sposobów wyszukiwania

Podobnie jak w Octopart, API Nexar jest elastyczne pod względem sposobu wyszukiwania komponentu. Jeśli chcesz wykonać szerokie wyszukiwanie, możesz szukać po częściowym MPN albo na podstawie słów kluczowych. Jeśli dokładnie wiesz, czego chcesz, możesz wyszukać dokładny MPN.

W przypadku szerszego wyszukiwania operacją, której należy użyć w API, jest „supSearch”. Ta operacja wykona wyszukiwanie z dopasowaniem rozmytym.

query search { 

  supSearch (q: "Current sensor") { 

    hits 

    results { 

      part { 

        id 

        name 

        shortDescription 

      } 

    } 

  } 

} 

W powyższym przykładzie wyszukiwanie hasła „current sensor” zwróci liczbę trafień, identyfikatory części, nazwy oraz krótki opis komponentu. 

Operacja „supMultiMatch” przyjmuje listę do 100 części identyfikowanych przez MPN lub SKU (stock keeping unit) i rozpoznaje je zbiorczo. W przeciwieństwie do „supSearch”, przy użyciu „supMultiMatch” wszystkie częściowe dopasowania są ignorowane. To zapytanie dotyczy dwóch komponentów:

query MultiSearch { 

  supMultiMatch (queries: [ 

      {mpn: "SY55855VKG", limit: 1}, 

      {mpn: "BAV99-7-F"}, 

  ]) { hits  parts { id  name  mpn } } 

} 

Każdy wpis może być jedną pozycją BOM (bill of materials), więc cały wykaz materiałowy może zostać wyceniony bez konieczności otwierania przeglądarki.

Przykład 3: strona projektowa i zapisywanie danych z powrotem

Dane projektowe działają w ten sam sposób. Operacje z prefiksem des, takie jak „desWorkspaces”, sięgają do Twoich przestrzeni roboczych Altium 365. Ponieważ dane mają strukturę grafu, możesz podążać relacjami od punktu startowego na zewnątrz: od przestrzeni roboczej do zawartych w niej projektów, a od projektu do tego, co zawiera — od sieci i szczegółów komponentów po MCAD (mechanical computer-aided design) oraz informacje o położeniu. To Ty wybierasz, jak daleko chcesz zajść i ile danych z każdego etapu chcesz pobrać.

Odczyt to tylko połowa możliwości. Mutacja zapisuje dane: dodaje komentarz, przesyła projekt. Gdy operacja wymaga pliku, należy najpierw wysłać go do usługi plików Nexar pod adresem files.nexar.com/File/Upload, przekazując token zawierający zakresy design.domain, user.access i openid. W odpowiedzi otrzymujesz identyfikator ważny przez 24 godziny, o ile nie zostanie użyty, do którego odwołujesz się w samym żądaniu. Traktuj ten identyfikator jako niejawny, ponieważ jego format może ulec zmianie.

Co to zmienia w Twojej pracy

Wartość najłatwiej dostrzec, patrząc na to, jak trzy role już dziś spędzają swój czas i którą jego część API im odzyskuje.

Menedżer ds. zakupów lub kupiec

W firmie EMS (electronics manufacturing services provider) lub OEM (original equipment manufacturer) taka osoba potwierdza, że każda część w danym zleceniu jest dostępna na stanie, znajduje dystrybutora, który jest w stanie dotrzymać terminu dostawy, sprawdza cenę i składa zamówienie. Może to oznaczać kilka zamówień tygodniowo albo od 50 do 100 dziennie. Zazwyczaj praca odbywa się część po części, na podstawie arkusza kalkulacyjnego: wpisz jeden MPN, sprawdź dostępność, kliknij do dystrybutora i powtórz. Najpierw sprawdzani są autoryzowani dystrybutorzy, a wyszukiwanie rozszerza się na nieautoryzowanych brokerów tylko wtedy, gdy nic nie ma na stanie. Wielu kupców sprawdza wszystko drugi raz tuż przed złożeniem zamówienia, na wypadek gdyby coś zmieniło się z dnia na dzień.

Każdy z tych kroków ma swój odpowiednik opisany powyżej. Jedno zapytanie API zastępuje sto osobnych wyszukiwań. Użycie filtra „tylko autoryzowani” w API odpowiada temu samemu odruchowi „najpierw preferowani, potem rozszerz”, zapisanemu jako ustawienie zamiast drugiej rundy ręcznych poszukiwań. Ponowne sprawdzenie przed zamówieniem staje się zadaniem uruchamianym według harmonogramu, które alarmuje tylko wtedy, gdy coś się zmieniło. To, co odzyskujemy, to nie osąd kupca — on nadal pozostaje po jego stronie — lecz wpisywanie danych i przełączanie kart, które dziś ten osąd pochłaniają. Wcześniej wynegocjowane ceny kontraktowe nadal pozostają po stronie dystrybutora, więc API służy do tworzenia krótkiej listy i wychwytywania zmian, a nie do zastąpienia zamówienia zakupu.

Inżynier projektant

W OEM taka osoba odpowiada za cały cykl życia projektu elektrycznego — od diagramu blokowego, przez dobór komponentów, tworzenie schematu, projekt PCB i wydanie BOM. Ograniczenie nadrzędne jest proste: komponentu, którego nie da się kupić, nie da się uznać za dobry wybór projektowy. Dlatego Octopart jest używany jako etap walidacji, odpowiadający na pytanie „czy tę część da się faktycznie kupić i to z więcej niż jednego źródła?”, a także jako narzędzie odkrywania do wyszukiwania i porównywania kandydatów. Sama szerokość sieci dystrybucji jest tu sygnałem, ponieważ część dostępna tylko u jednego dystrybutora (albo u kilku dystrybutorów, ale z łącznym stanem magazynowym malejącym tydzień po tygodniu) stanowi ryzyko dla łańcucha dostaw, jeszcze zanim stanie się problemem zakupowym.

Po przeniesieniu tego do API taka kontrola przestaje być odruchem wykonywanym część po części i staje się bramką. Każda pozycja BOM może zostać sprawdzona przy wydaniu, a wszystko, co ma tylko jednego dystrybutora, niski stan magazynowy lub flagę cyklu życia, może zostać ujawnione zanim projekt zostanie zatwierdzony, a nie dopiero miesiące później. Obawa, której to przeciwdziała, jest konkretna i kosztowna: część przechodząca w EOL (end of life) po tym, jak została już uwzględniona w projekcie, co wymusza przeprojektowanie. Karty katalogowe można jednocześnie pobrać do własnych narzędzi, chociaż inżynierowie i tak będą weryfikować specyfikacje bezpośrednio z kartą katalogową — i słusznie.

Inżynier komponentów

Spotykany w średnich i dużych firmach OEM, szczególnie w branżach lotniczej, obronnej, motoryzacyjnej i medycznej, zwykle nie tworzy nowych projektów. Zarządza częściami już znajdującymi się w produkcji: utrzymuje aktualność biblioteki zatwierdzonych części, wychwytuje oznaki wycofywania, zanim przerodzą się w kryzys, oraz kwalifikuje zamienniki, gdy część zostaje wycofana. Części zagrożone trafiają na listę obserwacyjną sprawdzaną okresowo, częściowo dlatego, że wycofana część czasami wraca na rynek.

Lista obserwacyjna z mechanizmem samokontroli to najbardziej oczywista korzyść opisana w tym artykule. Zamiast polegać na tym, że ktoś będzie pamiętał o ponownym sprawdzeniu listy, zaplanowane zapytanie przegląda ją i zgłasza wyjątki. Ponieważ jedna aplikacja może jednocześnie obejmować obszar dostaw i projektowania, bibliotekę można odczytać po stronie projektowej i porównać z aktualnymi danymi rynkowymi po stronie dostaw w ramach tego samego uruchomienia, zamieniając okresowy ręczny audyt w stały raport. Octopart nadal otwiera proces selekcji, zamiast go zamykać: stąd pochodzą propozycje zamienników i informacje o dostępności rynkowej, natomiast weryfikacja formy, dopasowania, funkcji, zgodności i cyklu życia nadal odbywa się w narzędziach PLM (zarządzanie cyklem życia produktu) oraz u wyspecjalizowanych dostawców danych.

Co łączy tę trójkę

Żadna z tych person nie chce odwiedzać nowej strony internetowej. Oczekują, że odpowiedź pojawi się wewnątrz systemu, w którym już pracują — dokładnie wtedy, gdy jest potrzebna, bez konieczności, by ktoś szedł po nią „ręcznie”. Właśnie do tego służy API i jest to bardzo zbliżone do tego, jak Nexar opisuje własny cel: demokratyzować informacje i łączyć ludzi, aby mogli pracować wydajniej i podejmować trafniejsze decyzje biznesowe.

Jak zacząć

1. Zarejestruj się na portal.nexar.com przy użyciu adresu e-mail i hasła albo danych logowania Google, Facebook lub Altium 365. Organizacje, które już korzystają z SSO (single sign-on) w Altium 365, mogą logować się w ten sposób.
2. Utwórz organizację lub dołącz do istniejącej. Ten krok jest wymagany. Aby dołączyć do istniejącej organizacji, poproś jej członka o wysłanie zaproszenia.
3. Zaraz po rejestracji będzie dostępna gotowa aplikacja „Evaluation”, z której możesz korzystać. Możesz przejść do sekcji Apps i utworzyć dodatkowe aplikacje, jeśli chcesz.
4. W panelu API dostępne jest środowisko sandbox, które pozwala od razu rozpocząć eksplorację. Gdy będziesz gotowy, aby zintegrować dane ze swoim narzędziem lub aplikacją, przejdź do karty Authorization i pobierz dane uwierzytelniające.
5. Pobierz client ID i client secret z karty Authorization aplikacji. Są to statyczne dane uwierzytelniające. Traktuj secret jak hasło.
6. Wymień je na token dostępu. Nexar używa OAuth 2.0 (Open Authorization, wersja 2.0), a tokeny są ważne przez 24 godziny. Zapytania dotyczące dostaw używają grantu client credentials; zapytania design i adm używają grantu authorization code z zakresami OpenID, design.domain i user.access.

Przed napisaniem choćby jednej linijki kodu aplikacji możesz uruchomić wszystkie powyższe przykłady w edytorze GraphQL, takim jak Nitro (dawniej Banana Cake Pop) lub Postman. Endpointy to api.nexar.com/graphql dla API, identity.nexar.com/connect/token dla tokenów oraz files.nexar.com/File/Upload dla przesyłania plików. 

Co dalej

Zobacz API w działaniu. Rob Barton, Head of Platform API w Altium, omawia rozwój API Altium i wykonuje zapytania na żywo do danych dostawczych Octopart w podcaście OnTrack: Altium API Deep Dive: Opening PCB Data to Developers na YouTube.

Posłuchaj odcinka. OnTrack: The PCB Design Podcast, prowadzonego przez Zacha Petersona.

Poznaj model danych. Nexar Voyager zapewnia wizualną reprezentację schematu GraphQL.

Przeczytaj dokumentację. Pełna dokumentacja i glosariusz terminów są dostępne na support.nexar.com. Przykłady gotowego kodu są publikowane na GitHubie NexarDeveloper.