Getting Started

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 uses a REST interface over HTTP/HTTPS. The currently supported payload is application/JSON.

To Get Started

Follow the below steps - they will return USD currency from Dataloy VMS (illustrating that the API works properly):

https://[ip]:[port]/ws/rest/Currency?filter=currencyCode(EQ)USD

Request Format

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

Base URL

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

https://[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: Note: The root URL should NOT be hardcoded in your application to allow it to run against multiple servers. The "/ws/rest" part may also change in the future.

GET /Cargo/123456

Example: When the documentation refers to /Cargo, the full URL is https://[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

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.

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.

This example has been updated for API version 2.0.0 using date format yyyy-dd-MMThh:mi:ss to conform ISO 8601, versions prior to 2.0.0 has the following date format: yyyy-dd-MM hh:mi:ss

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

https://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).

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. 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.

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": [
        {
            "bookedQuantity": 10000        
        }
    ]
}

Insert an array element

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

Update an array element by including the key for the array element. The key is generated by the API when inserting a new element.

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

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:

https://ip:port/ws/rest/Document

All the dates are in the format yyyy-dd-MMThh:mi:ss to conform ISO 8601

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"
        }
    ]
}

Generic Dataloy API Fields

The following fields exist 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

The full URL of the entity.

modifiedDate

  • Last Modified Date

  • Object Changed by User or Recalculated by System

createdDate

Date for Object Creation

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 have 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

User key of the Dataloy VMS user that created the resource instnce initially.

changedById

User key of the Dataloy VMS user that updated the resource instance.

remarks[]

Array of remarks connected to the resouce instance

Date Format

From version 2.0.0 the date format has been changed to conform ISO 8601:

yyyy-MM-ddThh:mm:ss Example: 2014-01-01T00:00:00

Versions prior to 2.0.0:

Date format for JSON messages: yyyy-MM-dd hh:mm:ss Example: 2014-01-01 00:00:00 Date format for filtering: 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 introduction: http://www.json.org/

Tools for Simple Tests

Several tools are available to aid the testing of the API. This 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:

Firefox:

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).

PreviousAuthentication / AuthorizationNextData Model

Last updated