Entity Formats

The API supports three entity formats: CSV, JSON and XML. Generally, JSON is the preferred format, but XML is a fully valid option. CSV lacks proper support for null properties and should thus only be used in certain circumstances.

The request entity format is simply specified using the mandatory Content-Type header. The response format can be specified in two different ways.

1. You can add an Accept request header. This is the preferred option. Here is an example HTTP request using this method.

   GET /v1/~realm/products HTTP/1.1
   Host: test.onslip360.com
   Accept: application/json

2. Alternatively, you can add a .csv, .json or .xml extension to the resource you're accessing.

   GET /v1/~realm/products.xml HTTP/1.1
   Host: test.onslip360.com

   or

   GET /v1/~realm/products/1.xml HTTP/1.1
   Host: test.onslip360.com

An example best illustrates the different entity formats. This is an object that represents a company/account.

JSON

First up, JSON:

{
   "address" : "Kungsgatan 20\\n58218 Linköping",
   "alias" : "onslip.com",
   "business-category" : "event-services",
   "created" : "2014-01-28T08:57:21.191Z",
   "email" : "",
   "feature" : {
      "flags" : [
         "barcode-scanners",
         "auto-close-batch"
      ]
   },
   "name" : "Onslip Cloud AB",
   "org-number" : "123456-7890",
   "phone-number" : "0500-600 111",
   "updated-by" : 1,
   "updated" : "2017-02-02T13:01:35.120Z",
   "web-address" : "http://onslip.com"
}

XML

Second, XML. Primitive properties are stored as attributes while complex datatypes are child elements. Lists of primitive types use _ as element name; lists of complex type will use the object's name as element name.

<company address="Kungsgatan 20&#10;58218 Linköping"
         alias="onslip.com"
         business-category="event-services"
         created="2014-01-28T08:57:21.191Z"
         email=""
         name="Onslip Cloud AB"
         org-number="123456-7890"
         phone-number="0500-600 111"
         updated="2017-02-02T13:01:35.120Z"
         updated-by="1"
         web-address="http://onslip.com">
  <feature>
    <flags>
      <_>barcode-scanners</_>
      <_>auto-close-batch</_>
    </flags>
  </feature>
</company>

The server never sends null properties in responses, but for PATCH requests, the client may need to send a property with value null to clear it. In this case, the XML Schema property nil on an empty child element should be used to represent null.

<my-entity xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <my-prop xsi:nil="true" />
</my-entity

CSV

Finally, CSV:

"address","alias","business-category","created","email","feature.flags.0","feature.flags.1","name","org-number","phone-number","updated","updated-by","web-address"
"Kungsgatan 20
58218 Linköping","onslip.com","event-services","2014-01-28T08:57:21.191Z","","barcode-scanners","auto-close-batch","Onslip Cloud AB","123456-7890","0500-600 111","2017-02-02T13:01:35.120Z","1","http://onslip.com"

Note that null values cannot be represented in CSV, so don't use CSV for PATCH request payloads.

Binary Properties and Direct Property Access

Binary values can either be stored as Base64String properties (see Resources and Endpoints) or as File properties. Base64String values are returned inline, just like any other property, while File properties only contain metadata about the binary resource.

To access the content of File properties, append a colon-separated propery path at the end of the resource. For instance, in order to download the take-out icon from example.com location #1, issue a GET request to the following resource:

https://test.onslip360.com/v1/~example.com/locations/1:take-out-config:logo

Not only File properies are supported. You may also access Base64String properties (as application/octet-stream), subobjects and subarrays (as application/json, application/xml or application/csv) and primitives (as text/plain). Supported HTTP methods are GET (read), PUT (write) and DELETE (remove). PATCH is not supported. When a property is modified using PUT and DELETE in this manner, the server responds with the HTTP response code 205, Reset Content, in order to signal that the entity was updated and should be refresed by the client.

Binary resources are never converted to other formats (subobject and subarrays, however, are) and always sent as-is. To indicate that these responses should not be parsed by the client, a Content-Disposition header is added to the response. The header value is set to inline.

By appending !/ followed by a filename to the request path, the Content-Disposition value is changed to attachment. This is actually supported for all resourcees, not only for direct property access requests, and can be used to trigger a download/save dialog in web browsers.