Welcome to the Sayari Graph SDK for Node. The goal of this project is to get you up and running as quickly as possible so you can start benefiting from the power of Sayari Graph. In the new few sections you will learn how to setup and use the Sayari Graph SDK. We also document some example use cases to show how easy it is to build the power of Sayari Graph into your application.

Setup

The most up to date information about the Sayari Node SDK can be found in the associated GitHub repository.

Prerequisites

The only thing you need to start using this SDK are your CLIENT_ID and CLIENT_SECRET provided to you by Sayari.

Installation

There are 2 ways to install the python SDK.

The simplest of these is just to run npm install --save @sayari/sdk or yarn add @sayari/sdk. This will install the most recently published version of the client currently available via npm

Alternately, if you would like to install the very latest development version of the SDK, it is available in github.

Quickstart

This section will walk you through a basic example of connecting to Sayari Graph, resolving and entity, and getting that entity’s detailed information.

A selection of simple examples can be found here

Connecting

To connect to Sayari Graph, simply create a client and pass it your client ID and secret. Note: For security purposes, it is highly recommended that you don’t hardcode your client ID and secret in your code. Instead, simply export them as environment variables and use those.

1
const client = new SayariClient({ clientId: clientID, clientSecret: clientSecret })

Resolving an entity

Now that we have a client, we can use the Resolution method to find an entity. To do this we pass in the fields we want to match on. Full documentation of this endpoint can be seen in the API docs.

A request to resolve an entity with the name field matching “Victoria Beckham” is shown below:

1
const resolution = await client.resolution.resolution({name: "Victoria Beckham"});

Getting entity information

The resolution results themselves do contain some information about the entities found, but to get all the details for that entity we need to call the “get entity” endpoint.

A request to view the first resolved entity (best match) from the previous request would look like this:

1
const entityDetails = await client.entity.getEntity(resolution.data[0].entityId)

Complete example

After the steps above you should be left with code looks like this. We can add one final line to print all the fields of the resolved entity to see what it looks like.

1
import { SayariClient } from "@sayari/sdk";
2
3
// NOTE: To connect you most provide your client ID and client secret. To avoid accidentally checking these into git,
4
// it is recommended to use ENV variables
5
var clientID = process.env.CLIENT_ID;
6
var clientSecret = process.env.CLIENT_SECRET;
7
8
// Create an authenticated sayari client
9
const client = new SayariClient({ clientId: clientID, clientSecret: clientSecret })
10
11
// resolve an entity
12
const resolution = await client.resolution.resolution({name: "Victoria Beckham"});
13
14
// Get the entity details for the best match
15
const entityDetails = await client.entity.getEntity(resolution.data[0].entityId)
16
console.log(entityDetails)

Advanced

When interacting with the API directly, there are a few concepts that you need to handle manually. The SDK takes care of these things for you, but it is important to understand them if you want to use the SDK properly.

Authentication and token management

As you can see from the API documentation, there is an endpoint provided for authenticating to Sayari Graph which will return a bearer token. This token is then passed on all subsequent API calls to authenticate them. The SDK handles this process for you by first requesting the token and then adding it to all subsequent requests.

In addition to simplifying the connection process, the SDK is also designed to work in long-running application and keep the token up to date by rotating it before it expires. This is all handled behind the scenes by the client object itself and should require no additional action by the user.

Rate limiting

Some Sayari Graph endpoints are more compute intensive than others. To adequately allocate resources across customers and prevent service degradation, individual users are rate limited. It is very unlikely that you would ever encounter these limits when making requests manually or even in a single-threaded application. Typically, rate limiting will only come into play when making multiple API requests at the same time.

When a request is rate limited, the API will respond back with a 429 status code as well as a ‘Retry-After’ response header that tells you how long to wait before making a subsequent request (i.e. 5s).

To make things simpler, the SDK handles this for you and will automatically wait and retry requests if a 429 is received.

Guides

You should now have all the tools you need to start using the Sayari Graph Node SDK yourself.