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.
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.
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
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.
"SecretKey": "your private secret key", //at least 16 characters
//generate system model
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.
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.
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
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.
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.
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.