RESTful API Config Introduction

#Introduction TODO write introduction

##Documentation legend

• Data type: { ... }
• Placeholder: [ ... ]

##Response structure Each response consists of the meta object and the result array called objects.

	{
		"meta": {
			"offset": {Number}, 
			"limit": {Number}, 
			"filteredCount": {Number},
			"totalCount": {Number},
			"next": {String|null},
			"previous": {String|null}
		},
		"objects": {Array[Object]}
	}

In addition each object in objects provides an ID and a resource URI.

	{
		"meta": {Object},
		"objects": [{
			"id": {Number},
			...
			"resourceUri": {String}
		}]
	}

The id is a unique ID and the resourceUri is a unique uri of an object and can be used to get access to it. The uri is the full path to the resource whereby the id is part of a specific resource path.

##Default header Accept=[response_type]
Currently the only supported type is "application/json"

##Default parameter for querying and filtering The following list of query parameter are available for each request and are useful to filter the result set of the response.

###limit The limit parameter is used to set the maximum number of objects in the result-set.

GET [base_url]/[path]/[resource]/?limit={Number}

###offset The offset parameter is used to get the results of a specific page. It starts at 0.

GET [base_url]/[path]/[resource]/?offset={Number}

###embed The embed parameter is used to embed a response with resources which are in relationship to a specific resource. So you are able to embed the fragment resource with all related modules.

GET [base_url]/[path]/[resource]/?embed=[embed_query]

The value of the embed parameter is a query in the following format. The following antlr grammar is a simplified version but should explain how a embed query is defined.

query
    : resource fieldList? parameterList? ('.' resource fieldList? parameterList?)*
    ;

fieldList
    : '[' field (',' field)* ']'
    ;

parameterList
    : '(' filter '_' value (',' filter '_' value)* ')'
    ;

resource
    : 'pages'
    | 'fragments'
    | ...
    ;

field
    : 'title'
    | 'uri'
    | ...
    ;

filter
    : 'offset'
    | 'limit'
    | ...
    ;

value
    : [a-zA-Z0-9]+
    ;

The following example shows how to embed an application with max 12 pages where just the page title and its URI is requested. In addition each embedded page contains all its fragments.

pages[title,uri](offset_0,limit_12).fragments

As you can see a query contains reserved special characters so it is required to encode it.

GET [base_url]/config/applications/0?embed=pages[title,uri](offset_0,limit_12).fragments

Now you get the following response.

{
    "meta": {
        "previous": null,
        "next": null,
        "offset": 0,
        "limit": 20        
    },
    "objects": [{
        "id": 0,
        "title": "Example application title",
        "pages": {
           "meta": {
               "previous": null,
               "next": null,
               "offset": 0,
               "limit": 12
           },
           "objects": [{
               "id": 0,
               "title": "Home",
               "uri": "home",
               "fragments": {
                   "meta": {},
                   "objects": []
               },
               "resourceUri": "..."
           }]
        },
        "resourceUri": "..."
    }]
}