Getting Started with Dataloy REST API

Getting Started with Dataloy REST API (Application Programming Interface) provides an introduction to the Dataloy API directed towards developers and IT personnel. Basics, such as how to obtain, submit and modify data, are explained.

Dataloy’s API use a REST interface over HTTP/HTTPS. The currently supported payload is application/JSON.

Chapter Contents:

Prerequisites

API installed in a test environment.
Username and Password or a HTTP request for refreshing OAuth 2.0 token

To Get Started

Follow the below steps to do your first request. It will return USD currency from Dataloy VMS (illustrating that the API works properly):

Either
1. open the following URL in a web browser
```
http://username:password@[ip]:[port]/ws/rest/Currency?filter=currencyCode(EQ)USD
```
  1. Change Username
  2. Password
  3. IP-Address
  4. Port
2. or use a browser plugin such as Postman, REST Console, Advanced REST client or similar to do the same.
  Note: HIGHLY recommended when exploring the API.

Request Format

For POST and PUT requests the payload must be JSON and the Content-Type be set to application/json.

Authentication

New customers are setup with OAuth 2.0. If you are developing an integration for multiple customers, it needs to support both OAuth 2.0 and Basic authentication.

More information can be found here: Authentication/Authorization

Base URL

The base URL is customer specific. To obtain the IP-address and port for the specific API installation, please contact Dataloy.

http://[ip]:[port]/ws/rest

IMPORTANT: All URLs in this documentation is relative to the root URL stated below. The HTTP method will be written in front of the relative URL:

GET /Cargo/123456

Example:
When the documentation refers to /Cargo, the full URL is http://[ip]:[port]/ws/rest/Cargo.

General URL Structure

Resources (for example: Voyage, Document, ExchnangeRate), have a similar general URL structure.

Example:

In the table below "/Entity" represents the name of an entity type like "/Cargo" or "/Voyage".

Relative URL	Methods	Description
/Entity	GET, POST	Represents the collection of entities of the given type. GET will return a filterable array of entities of that type. These entities will be "minimized" and sometimes contain only the "key" and "self" properties. POST will insert a new entity of that type into the collection.
/Entity/{key}	GET, PUT, DELETE	Represents a single entity of the given type, identified by "key". GET will return the full representation of that entity. PUT will update the given entity. A PUT request may contain only the changed properties, and will return the full object after the change. From API version 3, PUT will also update Sub-objects, previous versions are limited to object by object updating. For API versions prior to version 3, Sub-objects should NOT be included in PUT requests. DELETE will return 200 OK and an empty body when successful. Not all entities can be be deleted.

Exception Handling

Dataloy's API return HTTP status codes in the HTTP header and provides additional information in the body in JSON format.

{
	"statusCode": 400,
	"statusText": "Bad Request",
	"message": "Missing field(s) in json body. All fields are required.",
	"date": "2013-02-05T09:49:52",
	"statusFamily": null,
	"method": null,
	"uri": null
}

Retrieve Data from Dataloy API

Information is retrieved by using a GET request on a URL. Each resource has it’s own URL. The API also supports searching resource specific parameters.

GET request on a URL:

Example:

The following GET request on example URL will return the document with ID 2729538.

http://server.com/ws/rest/Document/2729538

Filtering Data

Dataloy API is equipped with a strong generic filtering functionality. It is able to filter on almost any field visible in the API and filtering any resources returning an array of objects (see Filtering).

A simple example of filtering for currency USD

GET Currency?filter=currencyCode(EQ)USD

Sorting Data

Any property can be used for sorting the results from Dataloy API.

A simple example of sorting vessels by vesselName

Vessel?sort=vesselName(AS)

For more information see Sorting

The default limit of objects to be returned from Dataloy API is 2000. If more objects are required then pagination can be used. For more details: Pagination

Simple example of pagination:

Voyage?pageNumber=1&limit=100

Adjust Number of Fields to be returned

Its possible to modify the fields returned from Dataloy API for more details: Adjust Number of Fields to be Returned from a Request

Modifying Data Through Dataloy API (PUT)

Use PUT to modify data through the API. Specify the URL of a resource and send the content to be modified in the body of the HTTP call. A successful PUT will return the same body as a GET on that resource. Excluded properties will be ignored. Excluded array elements will be removed. PUT will also update Sub-objects.

Examples:

Updating properties for a main object. In this case VoyageHeader

 {
    "doProfitLoss": 1.1,
    "tradeVoyageNo": 2345,
    "isBudget": true,
    "voyageStartDate": "2017-03-01T01:58:00",
    "referenceNo": "12341"
 }

Updating properties for a sub-object. In this case Voyage is the main object and Cargo is the sub-object

{
	"cargos": [
		{
            "key" : 123456789 
			"bookedQuantity": 10000			
		}
	]
}

Insert an array element

 {
   "remarks": [
       {
            "remarkTitle": "A Test remark title 1"
       }
    ]
 }

Insert a second array element by including the key for the first array element. Then add a second array element without a key.

 {
   "remarks": [
       {
            "key": 234581088,
			"remarkTitle": "A Test remark title 1 Updated"
       },
        {
            "remarkTitle": "A Test remark title 2"
       }
    ]
 }

Remove an array element. When having two elements in an array, you can remove one of them by removing the element in the PUT body

 {
   "remarks": [
       {
            "key": 234581088
       }
    ]
 }

Sub-objects

Inserting (POST) or updating (PUT) references to sub-objects can be done in different ways:
(All the examples below is using VoyageHeader as a main object and the specified company will be linked to the VoyageHeader.)

Specify the key to an existing sub-object

All existing objects has a key that is created by Dataloy API. This can be used for linking an existing object to another object.

 {
    "company":4601029
 }

Specify the code to an existing sub-object

A lot of the objects in Dataloy API has an unique code that can be used for identifying an object. This code can also be used for linking an existing object to another object.

 {
    "company": "09"
 }

Specify the sub-object

Another option for linking a sub-object is to provide the object to be linked.

 {
    "company": {
        "key": 163348582
    }
 }

Create a new object

The last option is to create a new sub-object and link it to a object in the same request. When excluding the key property a new object will be created.

 {
    "company": {        
        "companyCode": "1234",
        "companyName": "Test Company"
  	}
 }

Inserting Data Through Dataloy API (POST)

Send a POST request to a base resource URL with a body conforming with the minimum requirements of that resource.

Example:

POST request URL:

http://ip:port/ws/rest/Document

Body of Document HTTP POST

{
	"documentAmount": 0.0,
	"companyCurrencyAmount": 0.0,
	"sourceCurrencyAmount": 0.0,
	"documentDate": "2013-04-04T00:00:00",
	"documentType": "PMI",
	"invoicingStatus": "POS",
	"documentNo": "XXXXXX",
	"company": 10001,
	"documentCurrency": "USD",
	"documentText": "text here",
	"businessPartner": 20002,
	"documentLinesFromDocument": 
	[
		{
			"documentAmount": 0.0,
			"companyCurrencyAmount": 0.0,
			"sourceCurrencyAmount": 0.0,
			"sourceCurrency": "USD",
			"refDocument": "52011962",
			"documentLineText": "text here",
			"isAccountsPayable": "true",
			"businessPartner": "16959"
		}
	]
}

Webhooks

With webhooks you can subscribe to changes in VMS and data is sent to your endpoint when changes occur. For more information: Webhooks

Generic Dataloy API Fields

The following fields exists for all Dataloy VMS API resources:

Field Name	Description
key	The ID of the entity. This can be used to: request that entity at a URL of the form /Entitytype/{key} or to represent the entity in a POST or PUT request
self	The full URL of the entity.
modifiedDate	Last Modified Date Object Changed by User or Recalculated by System
createdDate	Date for Object Creation
codeProperty	Defines the code property of a resource. The value is the name of another property which can be used to identify the resource and is, in many cases, functionally equivalent to the "key" propery. Note: Not all resources has a codeProperty. Example: When setting a currency either an invoice the key (ID) of that currency or the currencyCode (i.e. the codeProperty of Currency) can be used.
createdById	UserID of the Dataloy VMS user that created the record initially.
remarks[]	Array of remarks for that object
externalObjectKey	String attribute to be used to link Dataloy key with external system key. Available since 5.49.0

Date Format

yyyy-MM-ddThh:mm:ss

Example:

2014-01-01T00:00:00

REST - Representational State Transfer

A quick introduction to REST is available at: http://www.infoq.com/articles/rest-introduction .

JSON - JavaScript Object Notation

JSON is a text format that is natively supported by Javascript. It is less verbose than XML and is easier for users to read. JSON is not written in order, so fields might change position between calls. A quick introdution: http://www.json.org/

Tools for Simple Tests

Several tools are available to aid testing of the API. These enables a payload to be sent to a URL with a specific type of request, for example GET, PUT, POST.

Examples of available tools (but NOT limited to):

Chrome:

Advanced REST client: https://chrome.google.com/webstore/search/advanced%20rest%20client
Postman: https://chrome.google.com/webstore/detail/postman-rest-client/fdmmgilgnpjigdojojpjoooidkmcomcm?hl=en-US

Firefox:

Poster: https://addons.mozilla.org/en-us/firefox/addon/poster/

Note: Dataloy recommends tools like JSONView to Chrome (to browse the API more conveniently when developing).

Documentation of API resources is currently in progress. Presently the reference documentation is manually updated. (More Information: Accounting Integration API).

Top
Back