Transitioning from RESTful API into GraphQL API

The Octopart v4 REST API is accessed by sending HTTP GET requests to proper API endpoints 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 /v4/rest/parts/match endpoint using a browser:

https://octopart.com/api/v4/rest/parts/match?apikey=V4_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/v4/rest/parts/match \
-d queries="[{\"mpn\":\"SN74S74N\"}]" \
-d apikey=V4_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 and the parameters that are URL encoded with the request.

The Nexar API is based on 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 GraphQL.

The authorization layer for the Nexar API is based on OAuth2. Using OAuth2, the client obtains an access token—a string denoting a specific scope, lifetime, and other access attributes. 

As Nexar API requests contain a body with a GraphQL-based string, it is difficult to show example requests in the browser using URL-encoded parameters as with the v4 REST search example above. 

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, using the command line with a GraphQL request can be difficult due to differences in various shell programs. 

Our recommendation for testing GraphQL queries is the Banana Cake Pop (BCP) IDE, which will be reviewed later in this guide.

The migration of an application using the Octopart v4 REST 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 v4 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 migrating from the Octopart v4 REST API to the Nexar API, use a browser and navigate to https://portal.nexar.com. Our Introduction to the Nexar API guide provides the next steps for creating an account and application.

The application(s) created in the Nexar Partner's Portal are distinct from the static v4 REST key used in the Octopart v4 API. The credentials for Nexar are managed under a subscription plan. This provides limits to the data that can be accessed, and the number of parts per month that are returned. You can learn more about Part Limits and When They Reset in our guide.

Upon creation, an account will have an Evaluation application which provides a lifetime free 1000 parts plan with access to most of our supply schema at no charge.

For more information about subscriptions that fit your intended API use case, please see our guide on Subscribing To A Self Serve Plan , or contact us at support@nexar.com.

As noted above, a GraphQL query is not as easy to make as a browser request, and using curl in the command line or similar tools can be difficult in understanding syntax problems in the construction of the GraphQL string. 

Fortunately, there exist integrated development environments (IDEs) that are available either in the browser or as stand alone applications that make it easy to construct and test queries in GraphQL.

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 guide on Setting Up Authorization in Banana Cake Pop (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 /v4/rest/parts/match endpoint. 

This query has a required argument named q - the string 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 -

We can tailor the API response to return only the data needed by the client, rather than the relatively fixed 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 to the Nexar v4 REST equivalent example, notice that the GraphQL equivalent query is preceded by the keyword ‘query’ (this is optional but recommended), and also contains more named fields in the body to approximate the behaviour of the v4 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 v4 REST 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 available Nexar queries. Towards 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!). 

You can use the GraphQL schema link as described above, or see the Voyager, our visual representation of the schema, for more information on the syntax (i.e. [ ] and !) to indicate arrays of types and required vs null content.

We also have a guide on How To Use Voyager.

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 v4 REST API supports the/partsendpoint.

Parts

There are four specific v4 REST API endpoints under /parts:

The Octopart v4 REST API example in this document uses the /v4/rest/parts/match endpoint with a query for MPNs matching "SN74S74N". 

With no additional arguments, the endpoint returns a limit of 3 parts that match the 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 with 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 /v4/rest/parts/match endpoint you can use supSearchMpn for matching a single MPN, or supMultiMatch to combine multiple MPNs into a single API request. See this guide on Supply Multi Match Query Size Limits for information on running multiple MPNs with supMultiMatch.

More v4 REST Endpoint Examples

The other v4 REST endpoints have these equivalent queries in Nexar:

A Nexar supply application is 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. Follow this guide for a Curl Example to Generate an Access Token.

The Client ID and Client Secret are generated when creating an application from a Nexar user account. You can find this information by following our guide on Authorization.

The access token returned by the identity server is a JWT token and can be examined for various claims including the time the token was issued, and 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.

Example Supply Applications

You can find our Nexar Playground GraphQL Query Examples, which can be accessed via the API playground button on the left column of the Nexar portal.  

For further information about how the Nexar API can be used to develop an application,  please see the Nexar First Supply Query 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 support@nexar.com.

For even more Nexar API information please also check out our guides. Here you can find more specific questions and documentation. 

If you cannot find an answer to your question, or have any feedback for us, you can get in touch by emailing support@nexar.com, or creating a support ticket.