A API Nexar, Explicada: o que é, como funciona e o que muda para as pessoas que a utilizam

Primeiro, o que é uma API

API significa interface de programação de aplicações. Uma pessoa usa um site clicando e lendo. Um programa não pode clicar, então ele precisa de uma janela de serviço para fazer uma pergunta precisa e receber uma resposta precisa em um formato que ele entenda. Essa janela é a API. O Octopart é um site em que nossos usuários podem pesquisar um componente eletrônico e visualizá-lo de todos os ângulos. Essa visualização inclui quem tem o componente em estoque, seu custo, status de ciclo de vida, atributos técnicos e muito mais. Você pode até pesquisar um componente para ver quais outros componentes são semelhantes a ele. A API Nexar entrega essas mesmas informações diretamente nos sistemas de software de negócios da sua empresa.

Benefícios de usar a API Nexar

• Integração às suas próprias ferramentas: Você pode incorporar dados atualizados da API Nexar diretamente em sistemas internos, como um sistema personalizado de gerenciamento de pedidos de compra ou um sistema de gerenciamento do ciclo de vida do produto.
• Mais do que dados de fornecimento: Além das informações de fornecimento, a API Nexar também recupera dados de projeto dos seus workspaces do Altium 365, de modo que uma única integração pode reunir dados de sourcing e de projeto.
• Consistência entre equipes: Todos que usam a mesma consulta recebem os mesmos valores de volta: o mesmo preço, o mesmo nível de estoque e as mesmas unidades no mesmo momento no tempo. Os números permanecem comparáveis entre pessoas, entre relatórios e ao longo do tempo.
• Automação em escala: A API Nexar permite consultar programaticamente até 100 peças por vez e executar até 300 consultas por minuto (potencialmente analisar 30.000 peças em um único minuto!)

A API Nexar

A API Nexar consiste principalmente em: 

• Dados de fornecimento são as informações de peças do Octopart: o lado de fornecimento da API oferece acesso a mais de 95 milhões de peças, com estoque, preços, status de ciclo de vida, lead time, datasheets, atributos técnicos, modelos CAD e sugestões de peças semelhantes, obtidos de distribuidores eletrônicos e atualizados diariamente. 

• Dados de projeto são voltados para clientes Altium, cobrindo o conteúdo dos seus workspaces de projeto, desde projetos até detalhes de componentes. O Modelo de Dados Nexar tem valor público aqui: Nexar Voyager. No modelo de dados, cada operação carrega um prefixo que informa o que ela abrange: sup para fornecimento, des para projeto e adm para administração da conta.

Exemplo 1: você descreve a resposta que deseja

Nexar usa GraphQL, uma linguagem de consulta para APIs. Em outras infraestruturas de API, você solicita um bloco fixo de dados, recebe tudo e escreve código para descartar o que não queria. Com GraphQL, você define o formato da resposta, e esse formato é o que retorna. Aqui está a forma documentada de uma pesquisa por MPN (manufacturer part number):

query MpnSearch { 

  supSearchMpn { 

    results { part { id  name  mpn } } 

  } 

} 

Leia em voz alta: execute uma pesquisa por números de peça do fabricante, diga-me quantos resultados houve e, para cada resultado, forneça o identificador da peça, o nome e o MPN. Nada além disso retorna. Peça mais, e você recebe mais. Em uma demonstração ao vivo da Altium, a pesquisa por um microcontrolador RA0E2 da família Renesas RA retornou a peça; ao adicionar especificações técnicas, confirmou-se que ela estava sinalizada como em conformidade com a RoHS (restrição de substâncias perigosas); ao adicionar o datasheet, retornaram um link para o arquivo, seu nome e sua data de criação, porque o Octopart classifica os datasheets disponíveis e pode retornar o melhor deles. Nada disso chegou até que fosse solicitado.

Exemplo 2: várias formas de pesquisar

Assim como no Octopart, a API Nexar é flexível na forma como você pode pesquisar um componente. Se quiser realizar uma pesquisa ampla, você pode pesquisar por um MPN parcial ou com base em palavras-chave. Se souber exatamente o que deseja, então pode pesquisar pelo MPN exato.

Para a pesquisa mais ampla, a operação que você deve usar na API é ‘supSearch’. Essa operação executará uma pesquisa com correspondência aproximada.

query search { 

  supSearch (q: "Current sensor") { 

    hits 

    results { 

      part { 

        id 

        name 

        shortDescription 

      } 

    } 

  } 

} 

No exemplo acima, a pesquisa por “current sensor” retornaria o número de resultados, os IDs das peças, os nomes e uma breve descrição do componente. 

A operação ‘supMultiMatch’ recebe uma lista de até 100 peças, identificadas por MPN ou por SKU (stock keeping unit), e as resolve em conjunto. Diferentemente de ‘supSearch’, ao usar ‘SupMultiMatch’ todas as correspondências parciais são ignoradas. Esta consulta trata de dois componentes:

query MultiSearch { 

  supMultiMatch (queries: [ 

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

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

  ]) { hits  parts { id  name  mpn } } 

} 

Cada entrada pode ser uma linha de uma BOM (bill of materials), de modo que uma lista completa possa ser precificada sem que ninguém precise abrir um navegador.

Exemplo 3: o lado de projeto e a gravação de dados de volta

O lado de projeto funciona da mesma forma. Operações com o prefixo des, como ‘desWorkspaces’, acessam seus workspaces do Altium 365. Como os dados têm estrutura de grafo, você segue os relacionamentos a partir de onde começar: de um workspace para os projetos dentro dele e de um projeto para o que ele contém, desde nets e detalhes de componentes até MCAD (projeto mecânico assistido por computador) e informações posicionais. Você escolhe até onde navegar e quanto de cada parada trazer de volta.

Ler é apenas metade disso. Uma mutation grava: adicionar um comentário, fazer upload de um projeto. Quando uma operação precisa de um arquivo, você primeiro o envia para o serviço de arquivos da Nexar, em files.nexar.com/File/Upload, passando um token que carrega os escopos design.domain, user.access e openid. O que retorna é um identificador, válido por 24 horas se não for usado, ao qual você faz referência na própria solicitação. Trate esse identificador como opaco, porque seu formato está sujeito a mudanças.

O que isso muda no seu trabalho

O valor fica mais fácil de ver observando como três funções já gastam seu tempo e em qual parte desse tempo a API devolve valor.

O gerente de compras ou comprador

Em uma EMS (prestadora de serviços de manufatura eletrônica) ou em uma OEM (fabricante original do equipamento), essa pessoa confirma que cada peça em uma montagem está em estoque, encontra um distribuidor que possa cumprir a data de entrega, entende o preço e faz o pedido. Isso pode significar alguns pedidos por semana ou de 50 a 100 por dia. O trabalho normalmente é feito peça por peça a partir de uma planilha: digitar um MPN, verificar disponibilidade, clicar até o distribuidor e repetir. Os distribuidores autorizados são verificados primeiro, e a pesquisa só se amplia para corretores não autorizados se nada estiver em estoque. Muitos compradores fazem uma segunda verificação imediatamente antes de pedir, caso algo tenha mudado de um dia para o outro.

Cada uma dessas etapas tem um equivalente acima. Uma consulta de API substitui uma centena de pesquisas separadas. Usar o filtro somente para autorizados na API é o mesmo instinto de “preferidos primeiro, depois ampliar”, escrito como uma configuração em vez de uma segunda rodada de pesquisa manual. A reverificação antes do pedido se torna uma tarefa executada em agenda e que alerta apenas quando algo muda. O que se recupera não é o julgamento, que continua com o comprador, mas a digitação e a troca de abas que hoje o consomem. Os preços contratuais pré-negociados continuam com o distribuidor, portanto a API serve para pré-seleção e para detectar mudanças, não para substituir o pedido de compra.

O engenheiro de projeto

Em uma OEM, essa pessoa é responsável pelo ciclo de vida do projeto elétrico, do diagrama de blocos à seleção de componentes, captura esquemática, layout e liberação da BOM. Sua restrição principal é direta: um componente que não pode ser adquirido é um problema de projeto. Por isso, o Octopart é usado como etapa de validação, respondendo “essa peça realmente pode ser comprada, e em mais de um lugar?” e também como ferramenta de descoberta para encontrar e comparar candidatos. A abrangência entre distribuidores é, por si só, o sinal, porque uma peça estocada por apenas um distribuidor (ou com vários distribuidores, mas com o estoque total diminuindo semana após semana) representa um risco de cadeia de suprimentos antes mesmo de se tornar um problema de compras.

Executado via API, esse controle deixa de ser um reflexo peça por peça e se torna uma etapa de validação. Cada linha de uma BOM pode ser testada na liberação, e qualquer item com distribuidor único, estoque baixo ou sinalização de ciclo de vida pode ser destacado antes da aprovação do projeto, em vez de meses depois. O receio que isso aborda é específico e caro: uma peça entrar em EOL (end of life) depois de já ter sido incorporada ao projeto, forçando um redesenho. Datasheets também podem ser trazidos para as suas próprias ferramentas ao mesmo tempo, embora os engenheiros ainda devam verificar as especificações no próprio datasheet, como deve ser.

O engenheiro de componentes

Encontrado em OEMs de médio a grande porte, especialmente nos setores aeroespacial, de defesa, automotivo e médico, essa pessoa normalmente não cria novos projetos. Ela gerencia as peças já em produção: mantém atualizada a biblioteca de peças aprovadas, detecta obsolescência antes que se torne uma crise e qualifica alternativas quando uma peça é descontinuada. As peças em risco ficam em uma lista de monitoramento verificada periodicamente, em parte porque uma peça descontinuada às vezes volta ao mercado.

Uma watchlist com autoverificação é a vitória mais evidente neste artigo. Em vez de alguém ter de se lembrar de revisitar uma lista, uma consulta agendada a percorre e reporta exceções. Como uma única aplicação pode manter juntos os escopos de suprimentos e de projeto, a biblioteca pode ser lida no lado do projeto e comparada com dados de mercado em tempo real no lado de suprimentos na mesma execução, transformando uma auditoria manual periódica em um relatório contínuo. O Octopart ainda abre o funil, em vez de fechá-lo: alternativos candidatos e disponibilidade no mercado vêm daqui, enquanto a verificação de forma, ajuste, função, conformidade e ciclo de vida continua a acontecer em ferramentas de PLM (gerenciamento do ciclo de vida do produto) e provedores de dados especializados.

O que os três têm em comum

Nenhuma dessas personas está pedindo para visitar um novo site. Elas estão pedindo que a resposta chegue dentro do sistema em que já trabalham; no momento em que isso importa, sem que alguém tenha de ir buscá-la. É para isso que serve uma API, e isso está próximo de como a Nexar descreve seu próprio propósito: democratizar a informação e aproximar as pessoas para que possam trabalhar com mais eficiência e tomar decisões de negócios mais inteligentes.

Como começar

1. Registre-se em portal.nexar.com com um endereço de e-mail e senha, ou com credenciais do Google, Facebook ou Altium 365. Organizações que já usam SSO (single sign-on) com Altium 365 podem entrar dessa forma.
2. Crie ou participe de uma organização. Esta etapa é obrigatória. Para entrar em uma organização existente, peça a um membro que convide você.
3. Assim que você se registrar, haverá uma aplicação pré-configurada de “Evaluation” disponível para seu uso. Você pode navegar até Apps e criar aplicações adicionais, se desejar.
4. Há um ambiente sandbox dentro do painel da API que permite explorar imediatamente. Quando estiver pronto para integrar os dados à sua ferramenta ou aplicação, você pode ir até a guia Authorization e recuperar as credenciais de autenticação.
5. Copie o client ID e o client secret na guia Authorization da aplicação. Eles são credenciais estáticas. Trate o secret como uma senha.
6. Troque-os por um access token. A Nexar usa OAuth 2.0 (Open Authorization, versão 2.0), e os tokens duram 24 horas. As consultas de suprimentos usam o client credentials grant; as consultas de design e adm usam o authorization code grant com os escopos OpenID, design.domain e user.access.

Você pode executar todos os exemplos acima em um editor GraphQL, como Nitro (anteriormente Banana Cake Pop) ou Postman, antes de escrever uma única linha de código da aplicação. Os endpoints são api.nexar.com/graphql para a API, identity.nexar.com/connect/token para tokens e files.nexar.com/File/Upload para uploads. 

Para onde ir em seguida

Veja a API em ação. Rob Barton, Head of Platform API na Altium, apresenta a evolução da API da Altium e executa consultas ao vivo nos dados de suprimentos do Octopart no podcast OnTrack: Altium API Deep Dive: Opening PCB Data to Developers no YouTube.

Ouça o episódio. OnTrack: The PCB Design Podcast, apresentado por Zach Peterson.

Explore o modelo de dados. Nexar Voyager oferece uma representação visual do esquema GraphQL.

Leia a documentação. A documentação completa e um glossário de termos estão disponíveis em support.nexar.com. Exemplos práticos de código são publicados no GitHub NexarDeveloper.