Page Comparison

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

1. API installed in a test environment.
2. 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):

1. Either

   1. open the following URL in a web browser

      Code Block
      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".

/Entity

/Entity/{key}

Anchor
exceptionHandling exceptionHandling

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

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

Pagination

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

Anchor
modify modify

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.

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

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

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

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

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

 {
    "company":4601029
 }

 {
    "company": "09"
 }

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

 {
    "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

{
	"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:

key

self

modifiedDate

createdDate

codeProperty

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

Related Content

{dynamiccontentbylabel:showLabels=false|showSpace=false}