Article Content
Background
This article is a brief guide to understanding how to use the Nexar API for someone familiar with the Octopart v4/Nexar Legacy API. For simplicity, the Octopart v4/Nexar Legacy API will be referred to as the Octopart API in this guide. To start, we will review some critical differences between the two APIs before going into how you should migrate an existing application over to Nexar.
API Scopes
The Octopart API provides part data such as offers or technical specifications. The Nexar API contains this functionality under the "Supply" scope - these queries are prefixed by "sup". This guide focuses on the supply scope. However, it is also good to understand that multiple scopes, such as the "Design" scope, exist to avoid early issues. The design scope provides API access to design information available in Altium 365.
User-centric VS Organization-centric
In the Octopart API, users will have their API token to query the API. If you are part of a team, you will have to share login details or your token, which is not very secure. Alternatively, only one person had access to the API.
In contrast, the Nexar API is organization-centric, meaning an organization owns an API plan and has a team of users who each have access to the API. The organization can own multiple applications, each with credentials to query the API. If you were to have various applications, you could assign each application a separate part limit from your overall plan.
Access Tokens
The Octopart API has a static access token that does not expire to query the API. If this token were mistakenly exposed or stolen, somebody could maliciously use it indefinitely.
The authorization layer for the Nexar API implements OAuth2. Using OAuth2, you will need to obtain an access token. The access token is a string that contains the specific scope, lifetime, and other access attributes. By employing a more modern architecture featuring limited-time tokens (Nexar tokens are valid for 24 hours), the Nexar API offers enhanced security compared to the static tokens used by the Octopart API.
The most common and recommended grant type for OAuth2 is "client credentials". With this grant type, you pass in an application's given client ID and secret, which are static, to receive an access token in return.
Casing
The Octopart API uses snake casing (snake_casing); words are separated by underscores and are all lowercase. The Nexar API uses camel casing (camelCasing), where words aren't separated, and the first letter of a new word is capitalized apart from the first word.
Step-by-Step Migration
Migration of an application using the Octopart API to the Nexar API will require the following steps:
- Create a Nexar account and application
- Translate queries to the Nexar API's syntax
- Develop code to secure an access token
Step 1 - Nexar Accounts and Applications
To start migrating from the Octopart API to the Nexar API, navigate to Nexar and follow the on-screen instructions for signing up. For detailed instructions, please see the "Getting Started" section of our knowledge base. These articles will take you through signing up, making your first application, and finding the app's credentials.
When making your first application, you will need to select the "Supply" scope; you may also choose the "Design" scope. A "Design scope" is not required for this article but will give that application access to Altium 365 design information through the API.
By default, an application with the supply scope will be on a 1000-part-per-month plan with access to most of our supply schema at no extra charge. Please see this "Compare API Plans" page for an up-to-date overview of available plans.
Step 2 - Translate Queries
Now that you are signed up for Nexar and have made your first application, you are ready to query the Nexar API. To start, you will need to configure an environment to work in, and there are a couple of options.
We have one integrated into our portal. Go to Applications -> Details (For an application with the supply scope) -> IDE. There are a couple of pre-written queries here that you can run.
Nexar also hosts an integrated development environment (IDE) for the browser, based on Banana Cake Pop (BCP - a tool developed by ChilliCream to build and test GraphQL). To learn how to configure this tool to use your Nexar application credentials, please visit this article for using OAuth2 with the Nexar/BCP IDE. If you are error-free when fetching a token, then the IDE is ready to query the API.
Below are some example queries for both the Octopart API and Nexar API so that you can see the differences in syntax. As noted above, the Nexar API uses camel casing rather than snake casing, as the Octopart API does. Also, the initial query is prefixed by "sup".
| Query | Octopart API | Nexar API |
| For categories | query Categories { categories { name id path num_parts } } | query Categories { supCategories{ id name path numParts } } |
| For a given MPN | query mpn { search_mpn (q: "acs770") { hits results { part { id name short_description sellers { company { id name } offers { id inventory_level prices { quantity price } } } } } } } | query mpn { supSearchMpn (q: "acs770"){ hits results { part { id name shortDescription sellers { company { id name } offers { id inventoryLevel prices { quantity price } } } } } } } |
You can see the schema for the API in BCP by going to the "Schema Reference" tab, or if you would prefer a visual representation, we have a page called "Voyager" with the article "How to Use Voyager".
Step 3 - Creating Nexar Supply Applications
A Nexar supply application is simply a program or script written to make a series of HTTP requests to the Nexar API to collect and process the information contained in the responses. Before making these requests, the program must obtain an access token from the Nexar Identity Service. The endpoint for getting access tokens is "https://identity.nexar.com/connect/token". The access token returned by the identity server is a JWT token. It can be examined, if needed, for various claims, including when the token was issued and, most importantly, when it expires. Once a token expires, it will no longer allow access to the API, and a new token must be generated. Once an access token is generated, the program can make repeated API requests using the token until the token expires.
For further information about using the Nexar API to develop an application, please see the Nexar first supply query GitHub repository. As of the time of writing, we have examples here in C#, javascript, and python. This is a publicly available repository, one of several in the NexarDeveloper GitHub resource.
For more information on the Nexar API, please see our knowledge base with more guides, examples, and FAQs.
Was this article helpful?
That’s Great!
Thank you for your feedback
Sorry! We couldn't be helpful
Thank you for your feedback
Feedback sent
We appreciate your effort and will try to fix the article