From wiki.ginstr.com
Revision as of 17:20, 3 May 2018 by Mark (talk | contribs) (Created page with "{|align=right |__TOC__ |} =Import/export REST API= ==Format of primitive datatypes== The exported/imported XML data uses XML standard formats for <code>[http://docstore.mik...")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Import/export REST API

Format of primitive datatypes

The exported/imported XML data uses XML standard formats for status, number, date, time, dateTime.

Endpoint

Development server endpoint for import/export:

https://mydev.ginstr.com

Development server endpoint for authorization:

https://ssodev.ginstr.com

Production server endpoint for import/export:

https://my.ginstr.com

Production server endpoint for authorization:

https://sso.ginstr.com

Authentication

Most of the calls are authenticated via a ticket provided by the SSO server. The SSO ticket must be send in the Authorization header.

The following requests authenticate correctly:

POST api/something Authorization: 36c7f15db00940c172dbac871cd70657f68ebdf891a465

Create authentication ticket

To create a authentication ticket the SSO server must be used.

URL path

/login

HTTP Method

POST

HTTP headers

Name Description
Content-Type (required) application/xml; charset=utf-8
Accept (required) application/xml

Parameters

Name Description Sample
body (required) xml with login parameters
<login>  <username>john@testnomail.nomail</username>
  <password>gasdrteW12</password>
</login>

Response

Response is a ticket everything is ok.

<loginStatus>
  <code>0</code>
  <error>success</error>
  <errorDescription />
  <language>
    <description>Deutsch</description>
    <languageId>2</languageId>
    <resourceId>de</resourceId>
  </language>
  <ticket>64e1bb3addddc9001004246bc791d92f33cf57fa62fc92703922fd2369f3b894</ticket>
  <userId>56222</userId>
  <username>ginstr@test.bsp.com</username>
</loginStatus>

Error response

When the API returns error messages, it does so in XML. This might look like this:

<errors><message>No message body / missing argument</message> <code>1010</code></errors>
Code Text
1 User not found! / or wrong password
26 Invalid parameter specified: username or password
1010 No message body / missing argument

Import data

Import new data or data to update. The table data must be provided as xml file. It is also possible to provide binary data.

Before importing the data is validated. If validation fails error with description will be returned and no data is inserted or updated.

The xml data contains row elements. These rows have the optional attributes id<code> and <code>uniqueKey. uniqueKey can be a unique column groups as described here, or the field name of a unique single column.

If one of these attributes is set the data will be updated.

If there is no data under this id/uniqueKey the data will be inserted.

If none of these attributes is set the data will be inserted.

If insert or update will fail the response contains error with description. The response contains also a list of rows that were not inserted or updated.

URL path

api/data/import

HTTP Method

POST

HTTP headers

Name Description Sample
Authorization (required) SSO ticket. See here 36c7f15db00940c172dbac871cd70657f68ebdf891a465
body (required) multipart form-data with parameters: appId, file
------WebKitFormBoundaryi2UMBvV6RinqfJer
Content-Disposition: form-data; name="file"; filename="importTest.zip"
Content-Type: application/x-zip-compressed

multipart form-data parameters

Name Description Sample
appId (required) the id of the application in which data should be imported demoAllDataTypesReadOnly
file (required) the zip file with the data that should be imported. The must be provided as xml. Additionally it is possible to add binary data for pictures, videos, audio or other documents.

zip file structure

/${filename}.xml
/${tablename}/attachment1.jpg
/${tablename}/attachment2.jpg
/${tablename}/attachment.doc

Put xml file in root directory and binaries in directories with name of table.

Request Example
URL path: api/data/import
Body:
multipart form-data with parameters: appId, file | <pre><code>
------WebKitFormBoundaryi2UMBvV6RinqfJer
Content-Disposition: form-data; name="appId"

mainUser101019_importTest_28975b1221184cfaa870887847bb5a6d
------WebKitFormBoundaryi2UMBvV6RinqfJer
Content-Disposition: form-data; name="file"; filename="importTest.zip"
Content-Type: application/x-zip-compressed
</code></pre>

XML file

Format of an exported file is the following:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" version="1.0" 
      elementFormDefault="qualified"
      attributeFormDefault="unqualified" 
      targetNamespace="http://my.ginstr.com/api/schema/data" 
      xmlns:tns="http://my.ginstr.com/api/schema/data">
  <xs:element name="tables" type="tns:xmlContent"/>
  <xs:complexType name="xmlContent">
    <xs:sequence>
      <xs:element name="table" type="tns:xmlTable" minOccurs="0" maxOccurs="unbounded"/>
    </xs:sequence>
  </xs:complexType>
  <xs:complexType name="xmlTable">
    <xs:sequence>
      <xs:element name="name" type="xs:string"/>
      <xs:element name="application" type="xs:string"/>
      <xs:element name="header" minOccurs="0">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="column" type="tns:xmlColumnHeader" minOccurs="0" maxOccurs="unbounded"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
      <xs:element name="rows" minOccurs="0">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="row" type="tns:xmlRow" minOccurs="0" maxOccurs="unbounded"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
    </xs:sequence>
  </xs:complexType>
  <xs:complexType name="xmlColumnHeader">
    <xs:simpleContent>
      <xs:extension base="xs:string">
        <xs:attribute name="id" type="xs:string" use="required"/>
      </xs:extension>
    </xs:simpleContent>
  </xs:complexType>
  <xs:complexType name="xmlRow">
    <xs:sequence>
      <xs:element name="column" type="tns:xmlRowCell" minOccurs="0" maxOccurs="unbounded"/>
    </xs:sequence>
    <xs:attribute name="id" type="xs:string"/>
    <xs:attribute name="uniqueKey" type="xs:string"/>
    <xs:attribute name="created" type="xs:dateTime"/>
  </xs:complexType>
  <xs:complexType name="xmlRowCell">
    <xs:choice minOccurs="0">
      <xs:element name="value" type="tns:simpleCellValue"/>
      <xs:element name="list" type="tns:listCellValue"/>
      <xs:element name="ref" type="tns:referenceCellValue"/>
    </xs:choice>
    <xs:attribute name="id" type="xs:string" use="required"/>
  </xs:complexType>
  <xs:simpleType name="simpleCellValue">
    <xs:restriction base="xs:string"/>
  </xs:simpleType>
  <xs:complexType name="listCellValue">
    <xs:sequence>
      <xs:choice maxOccurs="unbounded">
        <xs:element name="value" type="tns:simpleCellValue"/>
        <xs:element name="email" type="tns:emailCellValue"/>
        <xs:element name="phone" type="tns:phoneCellValue"/>
        <xs:element name="ref" type="tns:referenceCellValue"/>
      </xs:choice>
    </xs:sequence>
  </xs:complexType>
  <xs:complexType name="emailCellValue">
    <xs:sequence>
      <xs:element name="name" type="xs:string" minOccurs="0"/>
      <xs:element name="email" type="xs:string" minOccurs="0"/>
    </xs:sequence>
  </xs:complexType>
  <xs:complexType name="phoneCellValue">
    <xs:sequence>
      <xs:element name="name" type="xs:string" minOccurs="0"/>
      <xs:element name="phone" type="xs:string" minOccurs="0"/>
      <xs:element name="info" type="xs:string" minOccurs="0"/>
    </xs:sequence>
  </xs:complexType>
  <xs:complexType name="referenceCellValue">
    <xs:choice minOccurs="0">
      <xs:element name="value" type="tns:simpleCellValue"/>
      <xs:element name="list" type="tns:listCellValue"/>
    </xs:choice>
    <xs:attribute name="id" type="xs:string"/>
  </xs:complexType>
</xs:schema>
Sample:
<tables>
        <table>
            <name>employees</name>
            <application>demoApp</application>
            <rows>
                <row id="employee1">
                    <column id="column1">
                        <value>John</value>
                    </column>
                    <column id="column2">
                        <value>Smith</value>
                    </column>
                    <column id="column3"/>
                </row>
                <row id="employee2">
                    <column id="column1">
                        <value>Jordan</value>
                    </column>
                    <column id="column2">
                        <value>Smith</value>
                    </column>
                    <column id="column3">
                        <ref id="employee1"/>
                    </column>
                </row>
            </rows>
        </table>
    </tables>

Description of columns

text, enum
<value>Text value</value>
status
<value>true</value>
Allowed values:
  • true
  • false
iBeacon
<value>ff:ee:dd:cc:bb:11</value>
number, dateTimeDiff
<value>10.36</value>
Number format: standard java with . as decimal separator and no thousands separator.
weekday
<list>
  <value>monday</value>
  <value>thursday</value>
</list>
Allowed values:
  • monday
  • tuesday
  • wednesday
  • thursday
  • friday
  • saturday
  • sunday
time
<value>10:30:00</value>
Time format: HH:mm:ss
date
<value>2016-10-30</value>
Date format: yyyy-MM-dd
dateTime
<value>2016-10-30T10:30:00+01:00</value>
DateTime format: yyyy-MM-dd'T'HH:mm:ssZZ
listOfTimes
<list>
  <value>10:30:00</value>
  <value>12:45:00</value>
</list>
Time format: HH:mm:ss
listOfDates
<list>
  <value>2016-10-30</value>
  <value>2017-01-03</value>
</list>
Date format: yyyy-MM-dd
listOfDateTimes
<list>
  <value>2016-10-30T10:30:00+01:00</value>
  <value>2017-01-03T10:30:00+01:00</value>
</list>
DateTime format: yyyy-MM-dd'T'HH:mm:ssZZ
phone
<list>
  <phone>
    <name>Contact name 1</name>
    <phone>+325671265442</phone>
    <info>Example phone</info>
  </phone>
  <phone>
    <name>Contact name 2</name>
    <phone>+325671265443</phone>
    <info>Example phone</info>
  </phone>
</list>
email
<list>
  <email>
    <name>Contact name 1</name>
    <email>john@gmail.com</email>
  </email>
  <email>
    <name>Contact name 2</name>
    <email>jane@gmail.com</email>
  </email>
</list>
gps
<value>10.36,20.23644</value>
attachments
<list>
  <value>image1.jpg</value>
</list>
Name of the file in folder ${tablename}
pointer
<ref id="rowId"/>
assignment
<list>
  <ref id="row1Id"/>
  <ref id="row2Id"/>
</list>

Response

Response is an empty body if everything is ok.

Error response
When the API returns error messages, it does so in XML. This might look like this:
<errors><error><message>missing create permissions</message> <code>14131</code> 
<error></errors>
Code Text
1012 SSO error
1010 No message body / missing argument
1011 illegal argument
1014 multipart data missed
1019 ginstr web disabled
1021 incorrect AuthToken
10000 invalid file extension
14000 table not found
14010 error while reading zip archive
14026 value modification is not supported for this data type
14130 One or more rows have invalid content
14131 missing create permissions
14132 no files for import found in archive
14133 fail duplicated table file name
14134 column required
14135 column unsupported format
14136 column value unique
14137 row id unique
14138 row id invalid table
14300 unexpected

Delete data by key

If the application has unique columns or unique column groups as described here, it is possible to delete documents by key.

URL path

api/data/doc/{appId}/{tableName}

HTTP Method

DELETE

HTTP headers

Name Description Sample
Authorization (required) SSO ticket. See here 36c7f15db00940c172dbac871cd70657f68ebdf891a465
Content-Type (required) application/xml; charset=utf-8
"key1" must define the column combination "column1", "column2" as unique.

Parameters

Name Description Sample
appId (required) (path) id of the application demoAllDataTypesReadOnly
tableName (required) (path) name of table allDataTable
body (required) xml with key parameters
<uniqueKeys>
<key id="key1">
 <column id="column1">
  <value>John</value>
 </column>
 <column id="column2">
  <value>Smith</value>
 </column>
</key>
<key id="key1">
 <column id="column1">
  <value>Mike</value>
 </column>
 <column id="column2">
  <value>Smith</value>
 </column>
</key>
</uniqueKeys>

Delete data by document id

URL path

api/data/doc/{docId}

HTTP Method

DELETE

HTTP headers

Name Description Sample
Authorization (required) SSO ticket. See here 36c7f15db00940c172dbac871cd70657f68ebdf891a465

Parameters

Name Description Sample
docId (required) (path) Document ID 36c7f15d-b00940c17-2dbac871-cd70657f68eb-df891a

Export data

URL path

api/data/export/{appId}/{tableName}

HTTP Method

POST

HTTP headers

Name Description Sample
Authorization (required) SSO ticket. See here 36c7f15db00940c172dbac871cd70657f68ebdf891a465
Content-Type (required) application/xml; charset=utf-8
"key1" must define the column combination "column1", "column2" as unique.

Parameters

Name Description Sample
appId (required) (path) id of the application demoAllDataTypesReadOnly
tableName (required) (path) name of table allDataTable
body (required) xml with parameters
<filter>
</filter>

XML file

Name Description Sample
filter (optional) read only specific data, not set means read whole table data
<filter>
</filter>
Request Example
URL path: api/
Body:
{
        "language":"de",
	"use00":"false",
  	"tz":"Europe/Berlin",
  	"filter":{}
}

Response

Response is a zip file containing the data requested.

See zip file structure and XML file

Error response

When the API returns error messages, it does so in XML. This might look like this:

<errors><message>Invalid 'tz'</message> <errorCode>90</errorCode></errors>
Code Text
1012 SSO error
1005 Invalid JSON
1010 No message body / missing argument
5001 Invalid 'tz'