Backend Web API

Web API for GrandNode gives an access to business data stored in GrandNode database. It is REST API OData 4.0. More info about Web API can be found on http://www.asp.net/web-api. Web API Core information: http://odata.github.io/odata.net/#04-01-basic-crud-operations 

Note: User should be familiar with GrandNode database structure.

Swagger

You are also able to use API with Swagger. You need to enable it in the App_Data/appsettings.json file and then you will be able to go to

http://yourstore.com/swagger/index.html and use the browser extension.

List of content

1. How to configure WebAPI in GrandNode

2. How to add API user in GrandNode

3. How to generate Web API Token

4. List of available methods

How to configure Web API in GrandNode

First of all we need to enable API in appsettings.json file. You will find it in App_Data directory in main directory of GrandNode. Edit appsettings.json file. 

"Api": {
    "Enabled": false,
    "UseSwagger": false,
    "SecretKey": "your private secret key", //at least 16 characters
    "ValidateIssuer": false,
    "ValidIssuer": "",
    "ValidateAudience": false,
    "ValidAudience": "",
    "ValidateLifetime": true,
    "ValidateIssuerSigningKey": true,
    "ExpiryInMinutes": 1440,
    //generate system model
    "SystemModel": true
  },

Enabled - True/False. Specify whether API is enabled or not.

UseSwagger - True/False. Define if you want to use Swagger. 

SecretKey - Enter your secret key. 

ValidateIssuer - True/False.

ValidIssuer - Specify the provider of the token.

ValidateAudience - True/False.

ValidAudience - Specify the audience. It's client, i.e the receiving party. 

ValidateLifetime - True/False.

ValidateIssuerSigningKey - True/False.

ExpiryInMinutes - Specify the expiration time of token. 

SystemModel - True/False.

Please note that you need to restart application after each change in appsettings.json file.

How to add API user in GrandNode?

In admin panel you will find new tab - Manage API users. Go to Admin panel -> System -> Manage API Users. Then you will see a list of API users. By default list is empty. To add new user, press the "Add new record" button. 

In the Email field you need to provide an existing, registered customer in GrandNode. In the next field you need to enter API user password. Please note that it's not account password, it's new password used only in API. You need to remember that you are not able to view this password after save. Number of asterisks is fixed, you will always see 4 of them, it's not related with the length of password. In the last checkbox you can specify if it's active or not. 

How to generate Web API Token in GrandNode?

To show you how to generate Web API Token I will use a Postman in free plan. Open it and create new request. 

After save you will see a new window. We need to modify some things in it. 

We need to change the request type from GET to POST. 

Then you need to provide a request URL - it will be http://yourstore.com/api/token/create.

In the Auth tab, set Auth type to No Auth. 

In the next tab we need to add new Header. 

In the Key field enter the Content-Type, in Value field enter the application/json, description is empty.

Last step is to provide our API user credentials. Go to Body tab, select "Raw" type and enter the API user email and password.

Please note that password has to be Base64 encoded. You can use this tool to encode password: http://www.utilities-online.info/base64/#.XDNUAVxKi70

{
    "email":"admin@yourstore.com",
    "password":"MTIzNDU2"
} 

And that's all. Just press the "Send" button and if do everything correctly you will see generated token, as it's shown below:

It's a token which you will use to Authenticate your POST requests. 

Patch requests

If you face problems with PATCH requests, please ensure that the ID of the object in the Key field is placed between inverted commas 'ID'. Otherwise, you will receive 404 errors after sending a request.

List of available methods

You may list all methods used for any object, by typing “odata/$metadata” in your store (http://StoreURL/odata/$metadata). As a result, you will get XML with a full list grouped with objects.