Click the below button for the API Reference page:
Big Red Cloud’s Public API provides two kinds of API: (1) REST and (2) ODATA.
An API access works like a regular Big Red Cloud user: you create a Big Red Cloud account with a company, create an API Key associated with a company and start working with the company via API very similarly to the way you work with our web application.
Getting Started
- Setup Big Red Cloud account
- Start with setting up a free trial or commercial account
B. Create your unique API Key associated with your company
2. Explore API
A. Follow CODE SAMPLES (C#, Java, PHP, Perl, NodeJS) for your favorite language for a fast start
B. Get familiar with Big Red Cloud entities structure available for API
C. Explore every API method available - Integrate your business
A. Use the API to integrate Big Red Cloud with your applications
Sandbox
Big Red Cloud does not provide a separate company slot within your Tenant/Subscription for API testing purposes. You are welcome to use Trial Tenant for that purpose.
Authentication
Big Red Cloud API uses HTTP Basic Authentication. With this authentication type in each request client have to provide Authorization header which contains a Base-64 encoded username and password. For Big Red Cloud API you need to specify an username as your API key:
“Authorization”: “Basic ” + base64_encode(API Key)
In most libraries, credentials can be specified in the request authentication section. In this case, specify username as your API key and set password to any string.
HTTP Headers
CONTENT-TYPE
For POST and PUT requests you have to specify the MIME type of the body of the request. Big Red Cloud API supports only application/json type:
Content-Type: application/json; charset=utf-8
HTTP Response Codes
Every response from BigRedCloud API includes HTTP status code which describes processing result of the requested operation.
2XX SUCCESS
200 OK
The request was successful. Used as a response to successful get and batch requests.
201 Created
The request has been fulfilled and resulted in a new resource being created. Used as a response to a successful create request.
204 No Content
The server successfully processed the request, but is not returning any content. Used as a response to successful update and delete requests.
4XX CLIENT ERROR
400 Bad Request
The request cannot be fulfilled due to bad syntax.
401 Unauthorized
API key is missing or invalid.
403 Forbidden
The provided credentials were successfully authenticated but that credentials still do not grant the client permission to access the resource.
404 Not Found
The requested resource could not be found. In particular, used as a response when get, update or delete requests address to entity that does not exist.
409 Conflict
Indicates that the request could not be processed because of concurrency conflict. Detailed information you can find in the section Handling concurrency < link to section >
422 Unprocessable Entity
Indicates that some business rule violated. See the response body for detailed message.
5XX SERVER ERROR
500 Internal Server Error
The server encountered an error while processing the request. See the response body for more details.
Concurrency
A concurrency conflict occurs when one user gets an entity to edit it, and then another user updates the same entity before the changes of the first user is accepted. If do not use detection of these conflicts, the last update overwrites other user’s changes.
To prevent this accidental data loss Big Red Cloud platform uses optimistic concurrency control: it allows concurrency conflicts to happen, and if they do then react in a proper way. For example, user A gets SalesEntry and changes the Total field. User B gets the same SalesEntry and changes the EntryDate field. Then user A calls service’s update operation for this entity and receives OK response. After that user B calls the same operation for the same entity. In this scenario user B receives a 409 Conflict response code. In this case user B has to get this, changed by user A, entity again, make the changes and call service’s update operation.
In order to implement optimistic concurrency control, each entity (supposes modifications) returns with a field timestamp – this field managed by Big Red Cloud platform at server-side and you cannot change it. For every update and delete operations you have to provide timestamp received in appropriate GET operation (for update – in request body, for delete – in URL).
When you update an entity, the timestamp field re-generated to a new unique value automatically at server side.
ODATA Features
This is not an ODATA API. This is REST API still; it supports several features from ODATA when querying data collections. The target collection is specified through a URL, and query operations such as filter, sort, paging, and projection are specified as System Query Options provided as query options. The names of all System Query Options are prefixed with a “$” character.
Please find detailed specification on querying ODATA collections by the link: https://www.odata.org/documentation/odata-v3-documentation/odata-core/#1023_Querying_Collections
Limitations
Big Red Cloud API supports following System Query Options:
$filter
$orderby
$top
$skip
$inlinecount
Only logical operators allowed from the set of Built-in Filter Operations.
All Built-in Query Functions are forbidden.
There are number of additional limitations for each specific entity. You can find description of these limitations in documentation for API entities: < link to dynamic documentation tbd >
Pagination
API limits the number of entities that it sends in a single response. The maximum number of entities in response is 100. Entities querying response’s body has following structure:
{
Count: (Total number of entities),
Items:
[ (List of entities) ],
NextPageLink: (Link to the next entities’ page)
}
Count field indicates the total number of available entities. This field contains a value only if $inlinecount System Query Option with a value of allpages was specified in the request URL. Otherwise the Count field is null.
Items field contains a list of entities for the current page.
NextPageLink contains a link to the next page of data. If current page is the last one, the NextPageLink contains null.
Create Operation
When the server creates a new entity, it includes the URL of the new resource in the Location header of the response. The template of this URL is:
Location: https://api.bigredcloud.com//v1/{Entity set name}/{Id}
For example, if you create a new Product, the Location header may have following view:
Location: https://api.bigredcloud.com//v1/Products/8
Which means that the created Product has identifier 8, and it is available by URL provided.
Batch Operations
Big Red Cloud API supports execution of multiple operations in a single request. Following operations are supported: create, update, delete. Only operations with entities of the same type can be grouped in one batch.
Request
The PUT method should be used for batch requests. The body of batch request has the next structure:
[
{
item: { (Information for item 1) },
opCode: (Operation code for item 1)
},
{
item: { (Information for item 2) },
opCode: (Operation code for item 2)
},
…
]
Create
item contains information about created entity.
opCode should be 1
Update
item contains information about updated entity. Fields id and timestamp are mandatory for all entities. Detailed information about timestamp field you can find in the section Handling concurrency < link to section >
opCode should be 2
Delete
item has the next structure:
{
id: (Id of deleted entity),
timestamp: (Timestamp of deleted entity)
}
opCode should be 3.
Response
Response contains a list of processing results for each entity in the batch request. Order of the result elements corresponds with the order of entities in the request. I.e. if entity was the third in the request array, result of processing for this entity would be third in the response array.
In spite of any error during processing specific entity, the response status code will be 200 OK. You have to examine the response body to find failed operations.
The body of batch response has following structure:
[
{
code: (HTTP status code for item 1),
id: (Id of created, updated or deleted entity for item 1),
message: (Error message for item 1)
},
{
code: (HTTP status code for item 2),
id: (Id of created, updated or deleted entity for item 2),
message: (Error message for item 2)
},
…
]
code attribute contains HTTP status code which describes result of specific entity processing. Description of status codes you can find in the section HTTP Response Codes.
id attribute contains identifier for processed entity. For update and delete operations this field contains the same value that the field id contained in appropriate request item. For create operations this field contains identifier of newly created entity.
message attribute contains a message of the error occurred during specific entity processing. If there were no errors (code field is 2xx) this field contains null.
Throttling Protection
Big Red Cloud API protected from throttling issue by limiting # of API call per API Key per time period.
There is only one limitation “per 1 hour per 1 API Key” equals to 1,000 API calls per 1 hour sliding period.
If you exceed this rate you will receive a HTTP 429 server response error code (too many client requests) with a message “You have exceeded the permitted number of API calls of 1,000 per hour. Future API calls will be ignored until the beginning of the next period”.
If you need more calls rate than provided, contact Big Red Cloud support team ().
Logical Structure
Big Red Cloud API reflects web application UI logical structure: same principle of Books, Book Transactions, Dictionaries, etc.
Fake entity – given for structure only
Real API entity
Note that purple boxes are fake entries represented for structure only where red boxes are boxes are real API entries.
C#
Trivial example
Following is a simple console C# application:
(do not forget to add System.Net.Http assembly as a project reference)
using System;
using System.Net.Http;
using System.Text;
namespace BigRedBook.Api.SimpleSamples
{
class Program
{
static void Main(string[] args)
{
// Initialize constants. Change values to suitable for you!
const string baseApiAddress = “https://app.bigredcloud.com//api/v1/”;
const string apiKey = “”;
const string entitiesName = “Products”;
// Create and initialize HttpClient client.
HttpClient client = new HttpClient { BaseAddress = new Uri(baseApiAddress) };
// Add Authorization header.
byte[] apiKeyAsBytes = Encoding.ASCII.GetBytes(apiKey);
string apiKeyBase64Encoded = Convert.ToBase64String(apiKeyAsBytes);
string authorizationHeaderValue = “Basic ” + apiKeyBase64Encoded;
client.DefaultRequestHeaders.Add(“Authorization”, authorizationHeaderValue);
// Make a call to API – retrieve entity with maximal Id.
const string odataQueryParameters = “$orderby=id desc&$top=1”;
string requestUri = String.Format(“{0}?{1}”, entitiesName, odataQueryParameters);
HttpResponseMessage response = client.GetAsync(requestUri).Result;
// Display result of response.
Console.WriteLine(“Status code: {0} {1}”, (int)response.StatusCode, response.StatusCode);
Console.WriteLine(“Content:”);
string contentAsString = response.Content.ReadAsStringAsync().Result;
Console.WriteLine(contentAsString);
Console.Write(“Press any key to continue…”);
Console.ReadLine();
}
}
}
Complex example
A complex example consists from two parts: a Visual Studio solution with examples and a Visual Studio solution with big red cloud API client library on C#. The client library is an intermediate object-oriented layer for rapid api usage. This is recommended way to work with big red cloud api. The API client library is going to be improved and supported according to future Big Red Cloud API releases.
API Client: https://github.com/BigRedCloud/apiclient-net
API Samples: https://github.com/BigRedCloud/apisamples-net
Java
Trivial Example
Following is console java application:
(do not forget to include commons-codec-1.8.jar library as a reference)
package bigredbook.api.simplesamples;
import java.io.*;
import java.net.*;
import java.util.*;
import org.apache.commons.codec.binary.Base64;
public class Program {
public static void main(String[] args) {
// Initialize constants. Change values to suitable for you!
final String baseApiAddress = “https://app.bigredcloud.com//api/v1/”;
final String apiKey = “”;
final String entitiesName = “products”;
HttpURLConnection client = null;
StringBuilder result = null;
Integer statusCode = null;
String statusMessage = null;
try {
// Make a call to API – retrieve entity with maximal Id.
final String odataQueryParameters = “$orderby=id desc&$top=1”;
String requestUri = baseApiAddress + ‘/’
+ String.format(“%1$s?%2$s”, entitiesName, odataQueryParameters);
// Create and initialize HttpClient client.
URI uri = new URI(requestUri.replace(” “, “%20”));
URL url = uri.toURL();
client = (HttpURLConnection) url.openConnection();
// Add Authorization header.
byte[] apiKeyAsBytes = apiKey.getBytes(“ASCII”);
String apiKeyBase64Encoded = Base64.encodeBase64URLSafeString(apiKeyAsBytes);
String authorizationHeaderValue = “Basic ” + apiKeyBase64Encoded;
client.setRequestProperty(“Authorization”, authorizationHeaderValue);
client.setRequestMethod(“GET”);
client.connect();
statusCode = client.getResponseCode();
statusMessage = client.getResponseMessage();
BufferedReader rd = new BufferedReader(new InputStreamReader(client.getInputStream()));
result = new StringBuilder();
String line = null;
while ((line = rd.readLine()) != null) {
result.append(line + ‘n’);
}
} catch (URISyntaxException e) {
e.printStackTrace();
} catch (MalformedURLException e) {
e.printStackTrace();
} catch (ProtocolException e) {
e.printStackTrace();
} catch (IOException e) {
e.printStackTrace();
} finally{
//close the connection
if(client != null) {
client.disconnect();
}
}
// Display result of response.
System.out.printf(“Status code: %1$s %2$s” + “rn”, statusCode, statusMessage);
System.out.println(“Content:”);
String contentAsString = result.toString();
System.out.println(contentAsString);
System.out.print(“Press any key to continue . . .”);
new Scanner(System.in).nextLine();
}
}
PHP
Trivial Example
class ApiClass {
// Initialize constants. Change values to suitable for you!
const BASE_API_ADDRESS = “https://app.bigredcloud.com//api/v1/”;
const API_KEY = “”;
const ENTITIES_NAME = “Products”;
const QUERY_PARAMETERS = ‘$orderby=id+desc&$top=1’;
public function requestApi()
{
//check for installed curl extension
if (!function_exists(‘curl_init’)) {
throw new Exception(‘CURL is not installed!’);
}
// Set authorization header.
$apiKeyBase64Encoded = base64_encode(API_KEY);
$authorizationHeaderValue = “Basic ” + $apiKeyBase64Encoded;
$requestUri = ENTITIES_NAME.’?’.QUERY_PARAMETERS;
//init connection
$ch = curl_init(BASE_API_ADDRESS.$requestUri);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(‘Authorization ‘.$authorizationHeaderValue));
$opts = array(
CURLOPT_RETURNTRANSFER => 1,
CURLOPT_TIMEOUT => 120,
CURLOPT_FAILONERROR => 1
);
curl_setopt_array($ch, $opts);
$response = curl_exec($ch);
curl_close($ch);
return $response;
}
}
NodeJS
Trivial Example
var http = require(‘https’);
var BASE_API_ADDRESS = “https://app.bigredcloud.com/”;
var BASE_API_HOST = “app.bigredcloud.com/”;
var API_KEY = “”;
var ENTITIES_NAME = “Products”;
var QUERY_PARAMETERS = ‘$orderby=id+desc&$top=1’;
var authorizationHeaderValue = new Buffer(API_KEY, ‘base64’);
var optionsget = {
host : BASE_API_HOST, // here only the domain name
port : 443,
path : ‘/api/v1/’ + ENTITIES_NAME + QUERY_PARAMETERS, // the rest of the url with parameters if needed
method : ‘GET’, // do GET
headers: { ‘Authorization’: authorizationHeaderValue }
};
console.info(‘Options prepared:’);
console.info(optionsget);
console.info(‘Do the GET call’);
// do the GET request
var reqGet = http.request(optionsget, function(res) {
//console.log(“statusCode: “, res.statusCode);
// uncomment this for header details
// console.log(“headers: “, res.headers);
res.on(‘data’, function(d) {
console.info(‘GET result:n’);
process.stdout.write(d);
console.info(‘nnCall completed’);
});
});
reqGet.end();
reqGet.on(‘error’, function(e) {
console.error(e);
});
