Migration from Octopart v3 API

The Octopart v3 API is based upon a series of service endpoints that implement a REST based API. It is accessed by sending HTTP GET requests to proper API endpoint with a static key used for authorization. Each endpoint is a URL on the web where you can access data by using a command line program like curl, a programming language like Python or Ruby, or even by viewing the URL in your browser.

For example, to search for a part by its mpn you can send a request to the /v3/parts/match endpoint using a browser:

https://octopart.com/api/v3/parts/match?apikey=V3_KEY&queries=[{%22mpn%22:%22SN74S74N%22}]&pretty_print=true

Or by using a command line program equivalent with curl:

curl -G http://octopart.com/api/v3/parts/match \
-d queries="[{\"mpn\":\"SN74S74N\"}]" \
-d apikey=V3_KEY \
-d pretty_print=true

The response to these API requests is an object encoded in JSON format that contains information that is related to the endpoint chosen and the parameters that are URL encoded with the request.

The Nexar API is based upon GraphQL – an open-source data query and manipulation language for APIs, and a server for fulfilling queries with data. The Nexar API is accessed by sending an HTTP POST request to a single endpoint (https://api.nexar.com/graphql) containing a body describing the request details in the GraphQL language.

The authorization layer for the Nexar API is based upon OAuth2. Using OAuth2, the client obtains an access token – a string denoting a specific scope, lifetime, and other access attributes. By employing a more modern architecture featuring limited time tokens (Nexar access tokens are valid for only 24 hours), the Nexar API offers enhanced security compared to the static tokens used by the v3 REST API.

Because Nexar API requests contain a body including a GraphQL based string, it is not generally possible to show example requests in the browser using URL encoded parameters as was the case with the v3 search example above, but it is still possible to show a command line equivalent using curl:

curl -g https://api.nexar.com/graphql \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d "{\"query\": \"query{ supSearchMpn( q:\\\"SN74S74N\\\" ) { hits results { part { mpn manufacturer { name homepageUrl } sellers { company { name } offers { prices { price quantity }}}}}}}\"}

In practice, the command line usage of a GraphQL request can be very difficult to get right due to the differences in various shell programs in escaping quotes. There is a better alternative to using a command line (or even browser URL) testing for GraphQL queries and that will be reviewed later in this guide.

Migration of an application using the Octopart v3 API to the Nexar API will require the following steps:

1. Create an account at portal.nexar.com along with a Nexar application (i.e. API access credentials)

2. Develop string queries in the GraphQL language that are equivalent to each v3 REST API request (note: some GraphQL queries may replace multiple REST requests)

3. Develop code to secure an access token from the Nexar application credentials

To begin the process of migrating from the Octopart v3 API to the Nexar API, use a browser and navigate to https://portal.nexar.com. The next steps for creating an account and an application are covered in the introduction video and also under the 'Getting Started' section of our FAQ.

The application(s) created in the Nexar Partner's Portal are distinct from the static v3 key used in the Octopart v3 API. These credentials are managed under an overall subscription plan that provides limits to both the data that can be accessed and the number of parts (per month) that are returned from searches. By default, the applications created with the supply resource enabled are managed under a 1000 parts per month plan with access to most of our supply schema at no charge. Please see the FAQ site referenced above or contact us at [email protected] for more information about subscriptions that fit your intended API use case.

As noted above, a GraphQL query is not easy to make as a simple browser request and the command line version using curl (or similar tools like Postman, Insomnia, and many many more) can be tedious and unhelpful in understanding syntax problems in the construction of the GraphQL string. Fortunately, there are integrated development environments (IDEs) that are available either in the browser or as stand alone applications that make it easy to rapidly construct and test queries in the GraphQL language.

Configuring the IDE

Nexar hosts an IDE for the browser at https://api.nexar.com/graphql that is based upon Banana Cake Pop (BCP - a tool developed by ChilliCream to build and test GraphQL). To learn how to configure this to use your Nexar application credentials visit the FAQ for using OAuth2 with the Nexar/BCP IDE. If there is no error from the ‘Fetch Token’ action the IDE is ready for the next step.

Creating Queries

All of the requests to the Nexar API will be in the GraphQL language. In its simplest form a request will contain the name of a query enclosed in braces:

{ supSearchMpn }

The supSearchMpn query is used in the example above as one of the Nexar equivalents to the /v3/parts/match endpoint. This query has a required argument named q - the string to be used for the match. Without this required argument the Nexar API will return a ‘bad request’ error:

{ supSearchMpn(q: “Search String”) }

With the required argument this query will be processed but will return nothing in the response. This is due to one of the key differences between REST API behavior and GraphQL - the objects returned from a GraphQL query contain only the content explicitly named in the body of the query. This feature of GraphQL allows us to tailor the API response to only the data needed by the client rather than a relatively fixed (and sometimes large) block of data typically generated by a REST API endpoint. The query body is also enclosed in curly braces and follows the query name:

{ supSearchMpn(q: “Search String”) { hits } }

Now when this query is processed by the Nexar API it will return the number of matches for the search string. Comparing this simple example to the Nexar v3 equivalent example, notice that the GraphQL v3 equivalent query is preceded by the keyword ‘query’ (this is optional but recommended) and also contains many more named fields in the body to approximate the behavior of the v3 REST endpoint.

Exploring the Nexar Schema

When the IDE is fully configured, you may try any Nexar query by entering it into the left side panel under “Operations” and click on run to get the response on the right panel.

In the Introduction section, the Nexar example is not an exact equivalent for the Octopart v3 example due to the omission of some fields that are available in the supSearchMpn query. For example, the octopart_url field is part of the /parts/match endpoint response but is not included in this query. How do you find what is available in the Nexar query and how to use it? The solution is to use the IDE to explore the GraphQL schema by clicking on the “Schema Reference” tab above the query on the top left panel.

By scrolling down the list you will see all of the available Nexar queries and toward the bottom is the detail on the supSearchMpn query. The (...) following the query name indicates that it takes arguments that are listed to the right and the SupPartResultSet is the type that is returned from the query. That type is linked and clicking it will reveal the details for that type. Looking further into this type you will eventually find the octopartUrl field (results: [supPartResult!], then part: supPart, then finally octopartUrl: String!). Follow the GraphQL schema link above for more information on the syntax used (i.e. [] and !) to indicate arrays of types and required vs null content.

Nexar Equivalents for REST Endpoints

Inside of the Nexar HTTP request body are typically one or more queries that are, effectively, the equivalent of the various endpoints that would be used by a REST API. Octopart v3 API supports 4 primary endpoints:

• /brands

• /categories

• /parts

• /sellers

Parts

There are four specific v3 API endpoints under /parts:

The Octopart v3 API example in this document uses the /parts/match endpoint with a query for mpns matching "SN74S74N". With no additional arguments, the endpoint returns a limit of 3 parts that match mpn using a <PartsMatchResponse object> structure containing extensive information for each matching part that includes:

• uid

• mpn

• Manufacturer information

• Brand information

• Octopart URL for the product detail page containing this part

• List of offers that contain extensive information about sellers, prices, inventory, packaging and more.

Using additional parameters in the http request can add even more information to the response. All of the content generated from these endpoints may be found in the schema for the Nexar queries shown in the right side of the table. For the /parts/match endpoint you can use supSearchMpn for matching a single MPN or supMultiMatch to combine multiple MPNs into a single API request (see the Size Limit FAQ for important information on running multiple MPNs with supMultiMatch).

More v3 Endpoints

The other v3 endpoints have these equivalent queries in Nexar:

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 these requests can be made the program must first obtain an access token from the Nexar Identity Service. Once an access token is generated, the program may use it to make repeated API requests until the token expires.

In the previous section of this guide, the IDE was configured to generate the access token needed to run Nexar queries interactively. The next section will describe how this process works outside of the IDE.

Nexar Access Tokens

The access tokens required by the Nexar API can be obtained by posting an HTTP request to the Nexar identity server:

Generating an Access Token FAQ

The Client ID and Client Secret are generated when creating an application from a Nexar user account. This information can be found by logging into portal.nexar.com and choosing application details on the applications page.

The access token returned by the identity server is a JWT token and can be examined, if needed, for various claims that include the time the token was issued and, most importantly, the time that the token expires. Once the token expires it will be refused by the Nexar API and a new token must be generated (Nexar access tokens are valid for 24 hours after creation).

Example Supply Applications

For further information about how the Nexar API can be used to develop an application, please see the Nexar first supply query repository on Github. This publicly available repository (one of several in the NexarDeveloper GitHub resource) contains examples of applications using the Nexar supply API in different programming languages. If you wish to see these examples in a programming language that is not yet in the repository, please let us know by sending an email to [email protected].

For even more Nexar API information please also check out the FAQ site. Here you can find more specific questions of the “How do I …” nature. There is also a discussion forum to ask questions not found (yet) on our FAQ site.