L'API Nexar, spiegata: cos'è, come funziona e cosa cambia per chi la utilizza

Per prima cosa, cos’è un’API

API sta per application programming interface. Una persona usa un sito web cliccando e leggendo. Un programma non può cliccare, quindi ha bisogno di una finestra di servizio per porre una domanda precisa e ottenere una risposta precisa in un formato che possa comprendere. Quella finestra è l’API. Octopart è un sito web in cui i nostri utenti possono cercare un componente elettronico e visualizzarlo da ogni angolazione. Questa vista include chi ha il componente a magazzino, il suo costo, lo stato del ciclo di vita, gli attributi tecnici e altro ancora. È persino possibile cercare un componente per vedere quali altri componenti sono simili. L’API Nexar fornisce le stesse informazioni direttamente nei sistemi software aziendali della tua società.

Vantaggi dell’utilizzo dell’API Nexar

• Integrazione nei tuoi strumenti: Puoi incorporare dati aggiornati dall’API Nexar direttamente nei sistemi interni, come un sistema personalizzato di gestione degli ordini di acquisto o un sistema di Product Lifecycle Management.
• Più dei soli dati di fornitura: Oltre alle informazioni sulla fornitura, l’API Nexar recupera anche i dati di progettazione dai tuoi workspace Altium 365, così una singola integrazione può riunire dati di sourcing e dati di progettazione.
• Coerenza tra i team: Chiunque utilizzi la stessa query riceve gli stessi valori: lo stesso prezzo, lo stesso livello di inventario e le stesse unità nello stesso momento nel tempo. I numeri restano confrontabili tra persone, tra report e nel tempo.
• Automazione su larga scala: L’API Nexar ti permette di eseguire query programmatiche su fino a 100 parti alla volta e di eseguire fino a 300 query al minuto (potenzialmente analizzando 30.000 parti in un solo minuto!)

L’API Nexar

L’API Nexar è composta principalmente da: 

• Dati di fornitura sono le informazioni sui componenti di Octopart: il lato supply dell’API fornisce accesso a oltre 95 milioni di parti, con disponibilità a magazzino, prezzi, stato del ciclo di vita, lead time, datasheet, attributi tecnici, modelli CAD e suggerimenti di parti simili, ricavati dai distributori elettronici e aggiornati quotidianamente. 

• Dati di progettazione sono destinati ai clienti Altium e coprono i contenuti dei tuoi workspace di progettazione, dai progetti ai dettagli dei componenti. Qui è utile pubblicamente il Nexar Data Model: Nexar Voyager. Nel modello dati, ogni operazione porta un prefisso che indica cosa interessa: sup per supply, des per design e adm per l’amministrazione dell’account.

Esempio 1: descrivi la risposta che vuoi ottenere

Nexar utilizza GraphQL, un linguaggio di query per API. Con altre infrastrutture API, richiedi un blocco fisso di dati, lo ricevi per intero e scrivi codice per scartare ciò che non ti serve. Con GraphQL, scrivi la forma della risposta, ed è proprio quella forma che viene restituita. Ecco la forma documentata di una ricerca per MPN (manufacturer part number):

query MpnSearch { 

  supSearchMpn { 

    results { part { id  name  mpn } } 

  } 

} 

Leggilo ad alta voce: esegui una ricerca sui codici componente del produttore, dimmi quanti risultati ci sono stati e, per ogni risultato, dammi l’identificatore del componente, il nome e l’MPN. Non viene restituito nient’altro. Se chiedi di più, ottieni di più. In una dimostrazione live di Altium, la ricerca di un microcontrollore RA0E2 della famiglia Renesas RA ha restituito il componente; aggiungendo le specifiche tecniche si è confermato che era contrassegnato come conforme RoHS (restriction of hazardous substances); aggiungendo il datasheet è stato restituito un link al file, il suo nome e la sua data di creazione, perché Octopart assegna un punteggio ai datasheet disponibili e può restituire il migliore. Nulla di tutto questo arriva finché non viene richiesto.

Esempio 2: più modi di cercare

Come Octopart, l’API Nexar è flessibile nel modo in cui puoi cercare un componente. Se desideri eseguire una ricerca ampia, puoi cercare un MPN parziale oppure effettuare una ricerca basata su parole chiave. Se invece sai esattamente cosa vuoi, puoi cercare l’MPN esatto.

Per la ricerca più ampia, l’operazione da utilizzare nell’API è ‘supSearch’. Questa operazione esegue una ricerca con fuzzy match.

query search { 

  supSearch (q: "Current sensor") { 

    hits 

    results { 

      part { 

        id 

        name 

        shortDescription 

      } 

    } 

  } 

} 

Nell’esempio sopra, la ricerca di “current sensor” restituirebbe il numero di risultati, gli ID delle parti, i nomi e una breve descrizione del componente. 

L’operazione ‘supMultiMatch’ accetta un elenco di fino a 100 parti, identificate tramite MPN o SKU (stock keeping unit), e le risolve insieme. A differenza di ‘supSearch’, quando utilizzi ‘SupMultiMatch’ tutte le corrispondenze parziali vengono ignorate. Questo esempio interroga due componenti:

query MultiSearch { 

  supMultiMatch (queries: [ 

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

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

  ]) { hits  parts { id  name  mpn } } 

} 

Ogni voce può essere una riga di una BOM (bill of materials), così un’intera distinta base può essere prezzata senza che nessuno apra un browser. 

Esempio 3: il lato progettazione e la scrittura dei dati

La parte design funziona allo stesso modo. Le operazioni con prefisso des, come ‘desWorkspaces’, accedono ai tuoi workspace Altium 365. Poiché i dati sono strutturati come un grafo, puoi seguire le relazioni verso l’esterno da qualunque punto di partenza: da un workspace ai progetti al suo interno, e da un progetto a ciò che contiene, che spazia dalle net e dai dettagli dei componenti fino alle informazioni MCAD (mechanical computer-aided design) e di posizionamento. Scegli tu fino a dove spingerti e quanta parte di ogni tappa riportare indietro.

La lettura è solo metà del lavoro. Una mutation scrive: aggiunta di un commento, caricamento di un progetto. Quando un’operazione richiede un file, devi prima inviarlo al file service di Nexar, all’indirizzo files.nexar.com/File/Upload, passando un token che include gli scope design.domain, user.access e openid. Quello che viene restituito è un identificatore, valido per 24 ore se non utilizzato, che referenzi poi nella richiesta stessa. Tratta quell’identificatore come opaco, perché il suo formato è soggetto a modifiche.

Cosa cambia nel tuo lavoro

Il valore è più facile da capire osservando come tre ruoli impiegano già il loro tempo e in quale parte di quel tempo l’API restituisce valore.

Il responsabile acquisti o buyer

In un EMS (electronics manufacturing services provider) o in un OEM (original equipment manufacturer), questa persona verifica che ogni parte di una build sia disponibile a magazzino, trova un distributore in grado di rispettare la data di consegna, comprende il prezzo ed effettua l’ordine. Può trattarsi di pochi ordini a settimana o di 50-100 al giorno. Il lavoro viene di solito svolto componente per componente partendo da un foglio di calcolo: si digita un MPN, si controlla la disponibilità, si clicca sul distributore e si ripete. I distributori autorizzati vengono controllati per primi e la ricerca si estende ai broker non autorizzati solo se non c’è nulla disponibile a magazzino. Molti buyer eseguono un secondo controllo immediatamente prima dell’ordine, nel caso in cui qualcosa sia cambiato durante la notte.

Ognuno di questi passaggi ha un equivalente qui sopra. Una query API sostituisce cento ricerche separate. L’uso del filtro “solo autorizzati” nell’API corrisponde allo stesso approccio “prima i preferiti, poi si amplia”, ma espresso come impostazione anziché come un secondo giro di ricerche manuali. Il ricontrollo prima dell’ordine diventa un’attività pianificata che gira automaticamente e avvisa solo quando qualcosa è cambiato. Ciò che si recupera non è il giudizio, che resta al buyer, ma il tempo oggi assorbito dalla digitazione e dal continuo passaggio tra schede. I prezzi contrattuali negoziati in precedenza restano comunque in capo al distributore, quindi l’API serve per la shortlist e per intercettare i cambiamenti, non per sostituire l’ordine di acquisto.

L’ingegnere progettista

In un OEM, questa persona gestisce il ciclo di vita della progettazione elettrica dal block diagram alla selezione dei componenti, dall’acquisizione dello schematico al layout e al rilascio della BOM. Il vincolo che governa il suo lavoro è semplice e netto: un componente che non può essere approvvigionato è un problema di progettazione. Per questo Octopart viene utilizzato come fase di validazione, per rispondere alla domanda “questo componente si può davvero acquistare, e da più di una fonte?” e come strumento di scoperta per trovare e confrontare candidati. L’ampiezza della rete di distributori è di per sé un segnale, perché un componente presente presso un solo distributore (o presso più distributori ma con inventario complessivo in calo di settimana in settimana) rappresenta un rischio per la supply chain ancor prima di diventare un problema di approvvigionamento.

Se eseguito tramite API, quel controllo smette di essere un riflesso componente per componente e diventa un gate. Ogni riga di una BOM può essere verificata al rilascio, e tutto ciò che ha un solo distributore, stock limitato o un flag di lifecycle può emergere prima della firma finale del progetto, anziché mesi dopo. Il rischio che questo affronta è specifico e costoso: un componente che va in EOL (end of life) dopo essere stato inserito nel progetto, imponendo una riprogettazione. I datasheet possono essere acquisiti contemporaneamente nei tuoi strumenti, anche se gli ingegneri continueranno comunque a verificare le specifiche direttamente sul datasheet, come è giusto che sia.

L’ingegnere dei componenti

Presente nelle OEM di medie e grandi dimensioni, in particolare nei settori aerospaziale, difesa, automotive e medicale, questa figura di solito non crea nuovi progetti. Gestisce invece i componenti già in produzione: mantiene aggiornata la libreria delle parti approvate, intercetta l’obsolescenza prima che diventi una crisi e qualifica alternative quando un componente viene dismesso. I componenti a rischio vengono inseriti in una watchlist che viene controllata periodicamente, anche perché talvolta un componente dismesso torna sul mercato.

Una watchlist con autocontrollo è il vantaggio più evidente di questo articolo. Invece di affidarsi alla memoria di qualcuno per tornare a controllare un elenco, una query pianificata lo percorre e segnala le eccezioni. Poiché un’unica applicazione può contenere insieme gli ambiti di fornitura e di progettazione, la libreria può essere letta dal lato progettazione e confrontata con i dati di mercato in tempo reale dal lato fornitura nella stessa esecuzione, trasformando un audit manuale periodico in un report continuativo. Octopart continua comunque ad aprire il funnel, non a chiuderlo: da qui arrivano i candidati alternativi e la disponibilità sul mercato, mentre la verifica di forma, adattamento, funzione, conformità e ciclo di vita continua a essere eseguita negli strumenti PLM (product lifecycle management) e presso fornitori di dati specializzati.

Cosa hanno in comune tutti e tre

Nessuna di queste figure vuole visitare un nuovo sito web. Chiedono che la risposta arrivi all’interno del sistema in cui già lavorano, proprio nel momento in cui serve, senza che qualcuno debba andare a recuperarla manualmente. È proprio a questo che serve un’API, ed è molto vicino a come Nexar descrive il proprio scopo: democratizzare le informazioni e mettere le persone in contatto affinché possano lavorare in modo più efficiente e prendere decisioni aziendali più intelligenti.

Configurazione iniziale

1. Registrati su portal.nexar.com con un indirizzo email e una password, oppure con le credenziali Google, Facebook o Altium 365. Le organizzazioni che già utilizzano l’SSO (single sign-on) con Altium 365 possono accedere in questo modo.
2. Crea o unisciti a un’organizzazione. Questo passaggio è obbligatorio. Per unirti a una già esistente, chiedi a un membro di invitarti.
3. Non appena ti registri, sarà disponibile un’applicazione “Evaluation” preconfigurata da utilizzare. Se lo desideri, puoi andare in Apps e creare applicazioni aggiuntive.
4. All’interno della dashboard API è presente un ambiente sandbox che ti consente di iniziare subito a esplorare. Quando sei pronto a integrare i dati nel tuo strumento o nella tua applicazione, puoi aprire la scheda Authorization e recuperare le credenziali di autenticazione.
5. Prendi il client ID e il client secret dalla scheda Authorization dell’app. Sono credenziali statiche. Tratta il secret come una password.
6. Scambiali con un access token. Nexar utilizza OAuth 2.0 (Open Authorization, versione 2.0) e i token hanno una durata di 24 ore. Le query di fornitura usano il grant client credentials; le query design e adm usano il grant authorization code con gli scope OpenID, design.domain e user.access.

Puoi eseguire tutti gli esempi sopra in un editor GraphQL come Nitro (in precedenza Banana Cake Pop) o Postman prima di scrivere una sola riga di codice applicativo. Gli endpoint sono api.nexar.com/graphql per l’API, identity.nexar.com/connect/token per i token e files.nexar.com/File/Upload per gli upload. 

Dove andare ora

Guarda l’API in azione. Rob Barton, Head of Platform API di Altium, illustra l’evoluzione dell’API di Altium ed esegue query dal vivo sui dati di fornitura di Octopart nel podcast OnTrack: Altium API Deep Dive: Opening PCB Data to Developers su YouTube.

Ascolta l’episodio. OnTrack: The PCB Design Podcast, condotto da Zach Peterson.

Esplora il modello dati. Nexar Voyager fornisce una rappresentazione visiva dello schema GraphQL.

Leggi la documentazione. La documentazione completa e un glossario dei termini sono disponibili su support.nexar.com. Esempi di codice completi sono pubblicati su GitHub di NexarDeveloper.