Home > API Overview > JSON API

JSON API

Our JSON API is intended to be used in server-server scenarios or in applications where it isn't practical to use our Javascript SDK.

Before you Begin

In order to use our API you will need to be assigned a unique Application ID and Secret Key that is unique to your application. This information will insure your application has the right level of access to the devices in the platform and help secure communication between the 2 platforms. You will be assigned a different Application Id and Secret Key in our stage and production environments.

You can make the calls to our JSON API using the programming language and platform of your choice, as long as it can handle HTTPS based request / response scenarios.

Constructing the Request

To help explain the process, we will be using a sample Application ID and Secret Key in our examples.

• Application ID = contoso-api
• Secret Key = 472cccd50bfdfbdf87ad8f632e5fadf5

There are 2 different base URLS we use, 1 in staging for the initial integration and continued testing, and 1 for production:

• Staging Environment: https://stage.bluelibris.com/sdk/v1/
• Production Environment: https://na.bluelibris.com/sdk/v1/

Creating the URL

Every request you make will be to execute a specific action in our environment, every action relates to an entity, such as a "realm". For example, to view a realm you will execute the realm.view action on the realm entity. The URL that you submit the request to is created by appending the entity name and action name to the base URL for the environment you are using. So, to carryout our realm view example, the URL for this call against the staging environment would be:

https://stage.bluelibris.com/sdk/v1/realm/view

Every invocation is an HTTP POST sending a JSON object in UTF8 encoding using a content-type of application/json, every response will also be of type application/json with a JSON object for the payload.

Creating the Request Content

Every request you make will have the same base object structure - specifying what action to take, your authentication token, and the rest of the parameters required by the specific action you are invoking:

{
	"action" : "realm.view",
	"data" : {
		"partner_token" : {},
		.... other parameters
	}
}

Creating the Authentication Token

The partner_token is a JSON object you fill in using your assigned Application Id, Secret Key, and Realm to provide proof that is is your organization making the web service call. The proof is computed by creating an HMACSHA256 digest of a string using the Secret Key assigned to your application.

UNDER NO CIRCUMSTANCES should your Secret Key ever be transmitted as part of any communication with our servers, it is only used on your server to generate the proof!

The string you will need to sign is created by concatenating the following information together in one long string:

• Application Id (assigned to you by Numera), we will use contoso-api as an example
• Nonce (the number of seconds that have elapsed since 1/1/1970 midnight in UTC) ... you can see an example from http://www.epochconverter.com/ , we will use 1420744697 in our example
• The action you are taking against the entity. For example, when calling realm.view as the API action this value would be view

Using the example information, our string we need to sign would be constructed as:

contoso-api1420744697view

You would then use your programming environment's libraries to generate an HMACSHA256 digest using the Secret Key assigned to your application. The Secret Key is never transmitted as part of your API request, it is only used in your server code to generate this proof. Typically your libraries will expect a set of bytes as the secret key which means you need to use your language's libraries to get the bytes represented by the string version of the Secret Key given to you.

The signature generate by your code needs to be Base64 encoded as well as cleaned to make it URL safe, some programming libraries do this for you, but here are the rules we use:

• Replace all + characters with - (dashes)
• Replace all / characters with _ (underscores)

A very simplified C# example:

private string GenerateProof(byte[] toSign, byte[] key) 
{
	byte[] rawSignature = new HMACSHA256(key).ComputeHash(toSign);
	string signature = Convert.ToBase64String(rawSignature).Replace('+','-').Replace('/','_');
	return signature;
}

private void SomeMethod() 
{
	string toSign = "contoso-api1420744697view";
	string secretKey = "472cccd50bfdfbdf87ad8f632e5fadf5";

	byte[] toSignBytes = Encoding.ASCII.GetBytes(toSign);
	byte[] key = Encoding.ASCII.GetBytes(secretKey);

	string proof = GenerateProof(toSignBytes, key);
}

Now that we have our proof, we can put together our partner_token object which contains the following properties on the JSON object:

• id - your Application Id
• r - your assigned Realm
• n - the nonce value used to create your proof
• p - the proof string we just created

Using our sample information, our request structure would now look like this, the proof string shown below is real and a good way for you to check your code can generate the proof properly:

{
	"action" : "realm.view",
	"data" : {
		"partner_token" : {
			"id" : "contoso-api",
			"r" : "Contoso",
			"n" : 1420744697,
			"p" : "DNFKKnuk0IWLsldvAPy3KxHsowSAsoSLZjjYm9j_2-o="
		},
		.... other parameters
	}
}

Making the Call

Now, for this specific API call the only parameter we need to send is the name of the realm we want to view, so the entire call would look like this:

{
	"action" : "realm.view",
	"data" : {
		"partner_token" : {
			"id" : "contoso-api",
			"r" : "Contoso",
			"n" : 1420744697,
			"p" : "DNFKKnuk0IWLsldvAPy3KxHsowSAsoSLZjjYm9j_2-o="
		},
		"realm" : "Contoso"
	}
}

We also have the URL from before: https://stage.bluelibris.com/sdk/v1/realm/view, so now we just make an HTTP POST to that URL using the body content above.

Here is a simple C# sample to make this call above.

Understanding the Response

You should always receive an HTTP status code of 200 if your call was able to be processed, otherwise you will receive a 404 if you constructed a bad URL or a 500 if something really severe went wrong. Otherwise, you should always receive a 200 status code with a JSON object in the body, which contains the following properties:

You are Ready

You are now ready to start making API calls. See the complete API documentation for a reference of the different actions you can invoke. Enjoy!