CrossmarX REST API version 1.0

The CrossmarX standard REST API provides a web services API for interacting with your CrossmarX application. It can be used for mobile applications and Web 2.0 projects.

 

 

 

 

1 Introduction

The CrossmarX standard REST API provides a web services API for interacting with your CrossmarX application. It can be used for mobile applications and Web 2.0 projects.

The API uses GET, POST and DELETE HTTP methods to communicate.

The general url to access the api is

HTTP(S)://YOURDOMAIN/engine/api/VERSION/

 

• GET method will in general get a response from the server without data being changed at the server.
• POST method does add or change data at the server.
• DELETE is used to delete data

The Mobile API does not implement other HTTP methods (like HEAD etc etc) . 

• Your HTTP requests to the API resource should contain the following information:
• An HTTP method GET, POST, DELETE or PUT
• A authorization token and/or optionally session cookies provided by the server.
• An HTTP ACCEPT header. The default is JSON.
• A content-type
• Optional JSON content or file streams

The API will respond with a HTTP Status Code and a response containing either a JSON formatted result object or a file resource.

{
"statusMessage":
    {
"errcode":0,
"message":"Ok"
},

    "timestamp":"2014-09-16T17:13:56.056Z",

    .....,
    .....

}

 

2 Quick Example

To test the API you can use tools like curl or corresponding tools for Windows. Or use browser extensions like DHC REST Client.
First get the domain where your application is hosted. Furthermore you need the correct version id.

To get an object from the server lets say a certain book from a blueprint class book with Id 76
we send a request to the server as

HTTP method: GET

https://YOURDOMAIN/engine/api/VERSION/record/book/76?loginname=antonio&password=2ScrtHx8

 

The server will return HTTP Status code 200 and a result json object:

{
"statusMessage":
  {
"errcode":0,
"message":"Ok"
},
  "timestamp":"2014-09-16T17:13:56.056Z",
  "record":
    {
      "class":"book",
      "key":"76",
      "data":{
        "Id":76,
        "Title":"George in the Jungle",
        "Writer":"Sheldon Allman",
        .....,
        .....

      }

    }

}

 

 

 

3 Overview of Version 1.0 calls

 

HTTP Method	API call	Comment
POST	login
GET	record/CLASS/ID	Get a single record
GET	query	Get a list of records using a query definition in JSON
GET	download/CLASS/ID/FIELD	Download a file
POST	record/CLASS	Insert a new record
POST	upload/CLASS/ID/FIELD	Update an record
DELETE	record/CLASS/ID	Delete an record

4 Dates and time

All dates should be coded conform http://www.w3.org/TR/NOTE-datetime 2014-09-16T17:13:56.056Z

5 HTTP Status Codes and Error Responses

Either when an error occurs or when a response is successful, the response header contains an HTTP code, and the response body usually contains:

The HTTP response code.
The message accompanying the HTTP response code.
The field or record where the error occurred (if the response returns information about an error)

 

5.1 HTTP response code Description

200	“OK” success code, for GET request.
201	“Created” success code, for POST request.
204	“No Content” success code, for a delete request.
300	The value returned when an external ID exists in more than one record. The response body contains the list of matching records.
304	The request content has not changed since a specified date and time. The date and time is provided in a If-Modified-Since header.
400	The request couldn’t be understood, usually because the JSON contains an error.
401	The session has expired or is invalid. The response body contains the message and errcode.
403	The request has been refused. Verify that the logged-in user has correct permissions.
404	The requested resource couldn’t be found. Check the URI for errors, and verify that there are no sharing issues.
405	The method specified in the Request-Line isn’t allowed for the resource specified in the URI.
415	The entity in the request is in a format that’s not supported by the specified method.
500	An internal CrossmarX Application Engine error.

 

 

 

6 The version key

The version key in the request refers to a combination of the API version and the blueprint version. You have to define the key in the backstage on the target server. In the backstage: go to Deployment - Rest API Settings. Each setting has three properties:

• Name
  The name can be used as the version key in your request
  
  
• API version
  Select one of the available API versions
  
  
• Blueprint version
  Select one of the available blueprint versions on this server.

 In case you are an external developer using the API, you have to ask the application manager to define the version key for you.

7 Authentication

The API can be used by anyone including mobile (and other type of) devices therefore it is best to avoid session since such devices may not support a cookie. So a per request authentication is better despite the overhead of authentication per request. To simplify this we support a token based authentication keys . By sending user credentials or the oAuth2 hash code, the server can check each the users rights at request.

 

7.1 Token based authentication

To get a identification token you first need to send a login request to the server. The response will contain an identification key. Add this identification key to each subsequent request by adding it as a request parameter or as "Authorization: Bearer" HTTP header.

The identification key is valid for a longer period specified by the CrossmarX Application developer in its blueprint.

Each response will have this identification key in it until it expires. The expiration time is defined by the application on the server. Can be hours, or many days depending on the security level.

An identification key can be prolongated or changed for security reasons. In this case it will be replaced by a new one by the server. The client will get a new identification key in the response and will use that for its upcoming requests.

 

HTTP method: POST
URI: /engine/api/VERSION/login

example:

https://yourapp.crossmarx.com/engine/api/54321/login

{
  loginname: "antonio", 
  password: "2ScrtHx8"
}

 

The server will return HTTP Status code 200 and a result JSON object:

{

    "statusMessage":{

        "errcode":0,

        "message":"Found"
    },

    "timestamp":"2015-09-16T17:13:56.056Z",

    "key":"17",
    "authhash":"XySS74OLpzxx4PghvJUGuCfdDhuiHu"

} 

 

The authhash is used to authorize a user's requests without sending user credentials.

Example:

GET /engine/api/54321/record/book/76?authhash=XySS74OLpzxx4PghvJUGuCfdDhuiHu

Or better add it to the HTTP headers of each subsequent request as a "Authorization: Bearer" like

Authorization: Bearer XySS74OLpzxx4PghvJUGuCfdDhuiHu

 

 

7.2 Authentication using credentials at each request.

It is also possible to send the credentials with each request.

engine/api/54321/record/person/227?loginname=antonio&password=2ScrtHx8

 

 

8 Sessions or Stateless

 

The API works stateless. No session tracking is performed with cookies.

 

9 Identifiers

 

Fields in a record are refered to with technical identifiers as described in data-field-identifiers

So if for example your blueprint has a clazz Book with fields "First name" and "Last name" you need to use them in a request as "First_name" and "Last_name".
A request might be:

/engine/api/34877/record/Book/89?fields=First_name|Last_name

 

10 Responses

Every reponse from the server has a HTTP status code @see HTTP Status Codes and Error Responses and also a StatusMesssage JSON structured message. Except for file downloads when only HTTP Status codes are returned.

Eeach response consists of a StatusMessage, a timestamp and optionaly a  key and/or a recordList or record

{

    "statusMessage":{

        "errcode":0,
"message":"Ok"

    },

    "timestamp":"2014-09-16T17:13:56.056Z",

    "authhash":"XySS74OLpzxx4PghvJUGuCfdDhuiHu",

    "key": "123",

    "recordList":[] or "record":{}

}

 

10.1 RecordList

A record list is list of records.

10.2 Record

A record consists of three items. The blueprint class, a key value and a data object of key value pairs. A data object uses the same identifiers as the fields in your blueprint.

{

    "class":"Person",

    "key":"342",

    "data":{

        "Id":342,

        "First_name":"George",

        "Age":32,

        .....,

        .....

     }

}

 

 11 Resource retrieval

Resources are: records or files.

Resources can be obtained from the server using HTTP get methods. A certain record is fetched using a HTTP get method , and a path referring to the record, or a query.

 

11.1 Get a single record

HTTP method: GET

URI: /engine/api/VERSION/record/CLASS/id

 

Example: GET /engine/api/54321/record/book/76

The server will return HTTP Status code 200 and a result JSON object:

{

    "statusMessage":{

        "errcode":0,

        "message":"Ok"

     },

     "timestamp":"2014-09-16T17:13:56.056Z",
     "authhash":"XySS74OLpzxx4PghvJUGuCfdDhuiHu",

     "record": {

        "class":"Book",

        "key":"76",

        "data":{

            "Id":76,

            "Title":"George in the Jungle",

            "Writer":"Sheldon Allman" ,

            "Cover_Image", "/29320/2014/22/cover.png",
            .....,

            .....

        }

    }

}

 

  

11.2 Get a single record containing selected fields

HTTP method: GET

URI: /engine/api/VERSION/record/CLASS/id?fields=FIELDS

(FIELDS is a list of field identifiers separated by a pipe delimiter) 

Example: GET /engine/api/54321/record/book/76?fields=Id|Title

The server will return HTTP Status code 200 and a result JSON object:

{

    "statusMessage":{

        "errcode":0,

        "message":"Ok"

    },

    "timestamp":"2014-09-16T17:13:56.056Z",

    "authhash":"XySS74OLpzxx4PghvJUGuCfdDhuiHu",

    "record": {

        "class":"Book",

        "key":"76",

        "data":{

            "Id":76,

            "Title":"George in the Jungle"

        }

    }

}

 

11.3 Get a list of records based on a query

 HTTP method: GET

URI: /engine/api/VERSION/query?querydef={}

 

The querydef argument is a JSON formatted string defining a query. A query definition consists of

• a class - defining the main class of your query
• result fields - the fields you need in the results record(s) [OPTIONAL]
• a filter - restricts the number of records [OPTIONAL]
• sort specs - define how the list of records is ordered [OPTIONAL]

Result fields, filter and the sort specs are optional.

{

    "class": "" ,
    "resultFields" : [],

    "filter": {},

    "sortSpecs": [] 
}

The class element has a string value containing the name of the class.

The resultFields element is a list of fields

The filter element is organized as a tree of filterLeafs and filterNodes

A filterLeaf is:

{field: "", operator: "", value: object }

A filterNode is:

{ operator: "", children: [] }

The children element is a list of filterLeafs or filterNodes

 

The operator in a filterNode is "and", "or" or "not" and is optional. If filterNode has no operator the and operator is used for all of its childeren.

 

The operator in a filterLeaf can be one of

the standard expression operators: ">","<", "=","<=", ">=",

database operatators: "like" , "is not null", "is null"

In the appendix all operations are listed and documented.

 

Example:

{

    "class": "order",

    "resultFields": ["Price", "Num"],

    "filter": {

        "operator": "and",

        "children": [

            {"field": "Num", "operator": "equals", "value": "20"},

            {"field": "Price","operator": ">","value": 121}

        ]

    },

    "sortSpecs": [

        {"field": "Price", "direction": "desc"},

        {"field": "Num", "direction": "asc"}

    ]

}

 

Use http://www.url-encode-decode.com/ to convert your JSON formatted querydef in case you want to test it with tools like curl.

The server will return HTTP Status code 200 and a result JSON object:

{
    "statusMessage":{

        "errcode":0,

        "message":"Ok"

    },

    "timestamp":"2014-09-16T17:13:56.056Z",

    "authhash":"XySS74OLpzxx4PghvJUGuCfdDhuiHu",

    "recordList":[

         {

             "class":"order",

             "key":"7",
"data":{

                 "Id":7,

                 "Price":"122",

                 "Num": "20"

             }

         },
         {

             "class":"order",

             "key":"29",

             "data":{

                 "Id":29,

                 "Price":"189",

                 "Num": "20"

             }

          }
    ]

}

 

Paging or limit results

A query can return a lot of recordse. You may require to display some part of the records returned by a query specifying a range Or would like to limit the number of records in the response. The REST Api enables this with two parameters.

• start The first row of data to retrieve, starting at 0
• end The last row of data to retrieve (exclusive)

So if you want to fetch the first 5 rows your request wlll be 

/engine/api/VERSION/query?start=0&end=5&querydef={} 

11.4 Download files

A blob can be downloaded by asking for the corresponding blob field in the blueprint. For example consider the following book record.

{

    "class":"Book",

    "key":"76",

    "data":{

        "Id":76,

        "Title":"George in the Jungle",

        "Writer":"Sheldon Allman" ,

        "Cover_Image", "/29320/2014/22/cover.png",
        .....

    }

}

 

To get the image /29320/2014/22/cover.png we just ask the corresponding field Cover image from the server.

HTTP method: GET
URI: /engine/api/54321/download/book/76/Cover_Image

This will return the file /29320/2014/22/cover.png located on the server.

 

12 Data mutation

 

12.1 Insert a record

A new record created by client is posted to the server. The server inserts the new record and generates a key value. 

HTTP method: POST
URI: /engine/api/VERSION/record/CLASS

Example:

/engine/api/54321/record/person

{
    Last_Name: "Kennedy", 
    City: "London" 
}

 

The server will respond with the key of this new record on the server

{

    "statusMessage":{

        "errcode":0,

        "message":"Ok"

    },

    "timestamp":"2014-09-16T17:13:56.056Z",

    "authhash":"XySS74OLpzxx4PghvJUGuCfdDhuiHu",

    "key": "317"

}

 

12.2 Update a record

 HTTP method: POST

URI: /engine/api/VERSION/record/CLASS/key

Example:

/engine/api/54321/record/person/317

{
    id: 317,
    Last_Name: "Kennedy", 
    City: "London",
    Street: "Oxford street"
}

 

The server will respond like

{

    "statusMessage":{

        "errcode":0,

        "message":"Ok"

    },

    "timestamp":"2014-09-16T17:13:56.056Z",

    "authhash":"XySS74OLpzxx4PghvJUGuCfdDhuiHu",

    "key":"317"

}

 

Only fields posted to the server will be updated at the server. So in the above example only

    Last_Name: "Kennedy", 
    City: "London",
    Street: "Oxford street"

Last_Name, City and Street are updated.

If you want to set the value to NULL use NULL.

Example:

/engine/api/54321/record/person/317

{
    id: 317,
    Last_Name: "Kennedy", 
    City: "London",
    Street: NULL
}

 

12.3 Upload files.

HTTP method: POST, contentType = multipart/form-data
URI: /engine/api/VERSION/upload/class/key/field

example:
/engine/api/54321/upload/book/23/Cover_Image

file

 

Example with curl:

curl -i -F filedata=@/home/user/myfile.jpg "http://localhost:8080/engine/api/54321/upload/person/78/Foto" 

 

12.4 Delete a record

HTTP method: DELETE

URI: /engine/api/VERSION/record/CLASS/key

example:

/engine/api/54321/record/person/317

The server will respond with the id of this deleted record on the server

{

    "statusMessage":{

        "errcode":0,

        "message":"Ok"

    },

    "timestamp":"2014-09-16T17:13:56.056Z",

    "authhash":"XySS74OLpzxx4PghvJUGuCfdDhuiHu",

    "key": "317"

}

 

 

Appendix A: Field operations

• "starts_with"
• "ends_with"
• "equals", "is", "="
• "greater", ">"
• "greater_or_equals", ">="
• "is_not_null", "not_null"
• "is_null", "null"
• "like"
• "not_equals", "is not", "<>"
• "not_in"
• "not_like"
• "smaller", "<"
• "smaller_or_equals", "<="

 

 

 

Appendix B: Status Message Error Codes

 

 

Code	Label
0	Ok
5	Server error
6	Illegal api version
7	Unknown application version
10	Error in request
20	Authentication failed
21	Not logged on
25	No permission
30	SQL Error
31	Locked by other user
32	Duplicate lock
33	Locked by other session
34	Data integrity violation
35	No such record
50	File upload failed
51	Image can not be stored