Client Server Protocol

#0 Preface

Version 1.3.0

History of changes

04.12.2014 14:00 - 1.0.0 - Initial version
21.12.2014 01:00 - 1.1.0 - Changed POST request body to JSON format, changed auth and user management API, added metadata search filter, replaces session keys with cookie handling, return documents as HTML, added/specified data types, added possibility to select a layer and a datatype for the metadata URLs, geodata datatype changes, bugfixes.
06.01.2015 15:00 - 1.2.0 - Removed junk geodata request, added filter operation for comment, merged location/radius and bbox based filter, replaced modified and creation time in geodata to begin and end time.
10.01.2015 01:00 - 1.3.0 - Basemaps, language phrases and other config merged to/added to a new config JS-API, replaced layer data in geodata responses with comment count.

General definitions

<name:datatype> = Placeholder with the name name and the data type datatype (see below).
No result = An empty array will be returned.
All requests sending JSON data to the server must send the following header: Content-Type: application/json

Data types

string = any kind of text
boolean = Values: true or false
int = Integer value, e.g. 123
langcode = Language code based on ISO 639-1 norm, e.g. de, en or nl
hash = 32 characters containing only letters and numbers, which is actually a hash encoded by a hashing algorithm.
wkt = Well Known Text - Geo data type, e.g. POINT(0 180)
datetime = Date and time formatted according ISO 8601, e.g. 2014-02-17T15:19:21+01:00.
html = HTML source code
service = Data type which specified the file format of the specified metadata URLs. This must be one of the supported metadata formats, e.g. wms, mf2, ...

Base URL

Base URL of the API is http://<domain>/api/internal/

#1 User management

##1.1 Authentification / Log in

Status: Partially specified / partially implemented (oauth method missing)

Available authentification methods are:

mmm - My Meta Maps Account
oauth - Provider: facebook, github, twitter, google

Request for mmm method:

POST /user/login/mmm
{
	"credentials": {
		"identifier": "<identifier:string>",
		"password": "<password:string>",
		"remember": <rememberMe:boolean>
	}
}

Note: the identifier can be either the user name or the email adress.

Request for oauth method (unspecified as of yet):

POST /user/login/oauth
{
	"credentials": {
		"provider": "<provider:string>",
		"key": "<key:string>"
	}
}

Note: The provider must be one of the providers listed above.

Response for all methods:

On success:

HTTP 1.1 200 OK
{
	"user": {
		"id": <id:int>,
		"name": "<name:string>",
		"email": "<email:string>",
		"language": "<language:langcode>"
	},
	"session": {
		"session": "<session:hash>",
		"lastActivity": "<timestamp:int>"
	}
}

On failure/error:

HTTP 1.1 403 Forbidden
{}

###1.2 Log out

Status: Specified / Implemented

Request: GET /user/logout

Note: Sending the session hash is mandatory only when the client doesn't accept cookies.

Response:

HTTP 1.1 200 OK
{}

##1.3 Reset password

###1.3.1 Request email with a link to reset the password

Status: Specified / Implemented

Request:

POST /user/remind/request/
{
	"email": "<email:string>"
}

Response:

On success:

HTTP 1.1 200 OK
{}

On failure/error:

HTTP 1.1 409 Conflict
{
	"email": "<errorMessage:string>"
}

####1.3.2 Reset the password user using the temporary access token

Status: Specified / Implemented

Request:

POST /user/remind/reset/
{
	"email": "<email:string>",
	"token": "<emailed_token:hash>",
	"password": "<password1:string>",
	"password_confirmation": "<password2:string>",
}

Response:

On success:

HTTP 1.1 200 OK
{}

On failure/error:

HTTP 1.1 409 Conflict
{
	"<nameOfField:string>": "<errorMessage:string>",
	...
}

##1.4 Registration

Status: Specified / Implemented

Request:

POST /user/register
{
	"name": "<name:string>",
	"email": "<email:string>",
	"password": "<password1:string>",
	"password_confirmation": "<password2:string>"
}

Response:

On success:

HTTP 1.1 200 OK
{}

On failure/error:

HTTP 1.1 409 Conflict
{
	"<nameOfField:string>": "<errorMessage:string>",
	...
}

##1.5 Change user data

###1.5.1 Change general user data

Status: Specified / Implemented

Request:

POST /user/change/general
{
	"name": "<name:string>",
	"email": "<email:string>",
	"language": "<language:langcode>"
}

Note: All parameters are optional, but there must be at least one of them specified.

Response:

On success:

HTTP 1.1 200 OK
{}

On failure/error:

HTTP 1.1 409 Conflict
{
	"<nameOfField:string>": "<errorMessage:string>",
	...
}

If not logged in:

HTTP 1.1 403 Forbidden
{}

1.5.2 Change password (regularily)

Status: Specified / Implemented

Request:

POST /user/change/password
{
	"old_password": "<old_password:string>",
	"password": "<new_password1:string>",
	"password_confirmation": "<new_password2:string>"
}

Note: old_password is not needed when the user has no password set (due to oauth authentification).

Response:

On success:

HTTP 1.1 200 OK
{}

On failure/error:

HTTP 1.1 409 Conflict
{
	"<nameOfField:string>": "<errorMessage:string>",
	...
}

If not logged in:

HTTP 1.1 403 Forbidden
{}

##1.6 Check user data

Status: Specified / Implemented

Request:

POST /user/check/
{
	"<key:string>": "<value:string>"
}

Available types of data (keys) you can check:

email: Checks whether the specified value (email adress) is not already in use.
name: Checks whether the specified value (user name) is not taken yet.

Response:

When value is valid / ok:

HTTP 1.1 200 OK
{}

When value is invalid / not ok:

HTTP 1.1 409 Conflict
{}

When request is wrong (e.g. wrong parameters):

HTTP 1.1 404 Not Found
{}

##1.7 Send keep-alive request for the session

Status: Specified / Implemented

Request: GET /user/keepalive

Response:

HTTP 1.1 200 OK
{
	"session": {
		"session": "<session:hash>",
		"lastActivity": "<timestamp:int>"
	}
}

#2 Configuration

Status: Specified / Implemented

Request: GET /config

Response:

On success:

HTTP 1.1 200 OK
Content-Type: text/javascript; charset=utf-8
var config = {
	"debug": <debugMode:boolean>,
	"locale": <language:langcode>,
	"basemaps": [{
		"url": "<url:string>",
		"name": "<name:string>"
	}, ...],
	"datatypes": {
		"<datatype:service>": "<name:string>",
		...
	}
};
var phrases = {
	"<key:string>": "<key:value>",
	...
};

On failure/error:

HTTP 1.1 404 Not Found

#3 Geo data sets and comments

##3.1 Adding geodata and comments

##3.1.1 Save data

Status: Specified / Implemented

Request:

POST /geodata/add/
{
	"url": "<url:string>",
	"datatype": "<datatype:service>",
	"layer": "<layerName:string>",
	"text": "<text:string>",
	"geometry": "<geometry:wkt>",
	"start": "<startTime:datetime>",
	"end": "<endTime:datetime>",
	"rating": <rating:int>,
	"title": "<title:string>"
}

Optional parameters:

geometry
start
end
rating
layer
title (only optional when URL is already existant, see chapter 4.1.2)
datatype (only optional when URL is already existant, see chapter 4.1.2)

Response:

On success:

See the response in chapter 4.2.

On failure/error:

HTTP 1.1 409 Conflict
{
	"<nameOfField:string>": "<errorMessage:string>",
	...
}

###3.1.2 Read metadata (check validity of URL)

Status: Specified / Implemented

Request:

POST /geodata/metadata/
{
	"url": "<url:string>",
	"datatype": "<datatype:service>"
}

Response:

On success:

*Note: In case isNew is set to true the user has to specify a title for the data set. There will be a suggestion provided in the entry geodata.metadata.title. In the other case the user can't specify a custom title.

HTTP 1.1 200 OK
{
	"geodata": {
		"id": <id:int>,
		"url": "<url:string>",
		"isNew": <isNewUrl:boolean>,
		"metadata": {
			"datatype": "<datatype:service>",
			"title": "<title:string>",
			"bbox": "<bbox:wkt>",
			"keywords": ["<keyword1:string>", "<keyword2:string>", ...],
			"beginTime": "<beginTime:datetime>",
			"language": "<language:langcode>",
			"copyright": "<copyright:string>",
			"author": "<author:string>",
			"publisher": "<publisher:string>",
			"endTime": "<endTime:datetime>",
			"abstract": "<abstract:string>",
			"license": "<license:string>"
		},
		"layer": [{
			"id": "<id:string>",
			"title": "<title:string>",
			"bbox": "<bbox:wkt>"
		}, ...]
	}
}

On failure/error:

HTTP 1.1 409 Conflict
{
	"<nameOfField:string>": "<errorMessage:string>"
}

##3.2 List of geo data sets (with search/filter options)

Status: Specified

Request:

POST /geodata/list/
{
	"q": "<keywords:string>",
	"bbox": "<bbox:wkt>",
	"radius": "<radiusInKm:int>",
	"start": "<start:datetime>",
	"end": "<end:datetime>",
	"minrating": <rating:int>,
	"metadata": <searchInMetadata:boolean>
}

Note: If metadata is set to false the keywords are only searched in the texts of the comments. Otherwise the metadata of the geodata is additionally used for searching. metadata is only relevant when q is set.

Optional parameters:

q
radius (defaults to BBox area)
start
end
minrating
metadata (default: false)

Response:

HTTP 1.1 200 OK
{
	"geodata": [{
		"id": <id:int>,
		"url": "<url:string>",
		"comments": <commentCount:integer>,
		"metadata": {
			"datatype": "<datatype:service>",
			"title": "<title:string>",
			"bbox": "<bbox:wkt>",
			"keywords": ["<keyword1:string>", "<keyword2:string>", ...],
			"beginTime": "<beginTime:datetime>",
			"language": "<language:langcode>",
			"copyright": "<copyright:string>",
			"author": "<author:string>",
			"publisher": "<publisher:string>",
			"endTime": "<endTime:datetime>",
			"abstract": "<abstract:string>",
			"license": "<license:string>"
		}
	}, ...]
}

###3.3 Auto-complete for the search keywords

Status: Specified

Request:

POST /geodata/keywords
{
	"q": "<keyword:string>",
	"metadata": <searchInMetadata:boolean>
}

Note: If metadata is set to false the keywords are only searched in the texts of the comments. Otherwise the metadata of the geodata is additionally used for searching.

Response:

HTTP 1.1 200 OK
{
	"keywords": ["<keyword1:string>", "<keyword2:string>", ...]
}

###3.4 Permanent links for search results

####3.4.1 Save permalink

Status: Specified

Request:

POST /geodata/search/save
{
	"q": "<keywords:string>",
	"bbox": "<bbox:wkt>",
	"radius": "<radiusInKm:int>",
	"start": "<start:datetime>",
	"end": "<end:datetime>",
	"minrating": <rating:int>,
	"metadata": <searchInMetadata:boolean>
}

Optional parameters:

q
radius (defaults to BBox area)
start
end
minrating
metadata (default: false)

Response:

HTTP 1.1 200 OK
{
	"permalink": "<permalink>"
}

####3.4.2 Load permalink

Status: Specified

Request: GET /geodata/search/load/<id:hash>

Response:

HTTP 1.1 200 OK
{
	"permalink": {
		"q": "<keywords:string>",
		"bbox": "<bbox:wkt>",
		"radius": "<radiusinKm:int>",
		"start": "<start:datetime>",
		"end": "<end:datetime>",
		"minrating": "<rating:int>",
		"metadata": <searchInMetadata:boolean>
	},
	"geodata": [{
		"id": <id:int>,
		"url": "<url:string>",
		"comments": <commentCount:integer>,
		"metadata": {
			"datatype": "<datatype:service>",
			"title": "<title:string>",
			"bbox": "<bbox:wkt>",
			"keywords": ["<keyword1:string>", "<keyword2:string>", ...],
			"beginTime": "<beginTime:datetime>",
			"language": "<language:langcode>",
			"copyright": "<copyright:string>",
			"author": "<author:string>",
			"publisher": "<publisher:string>",
			"endTime": "<endTime:datetime>",
			"abstract": "<abstract:string>",
			"license": "<license:string>"
		}
	}, ...]
}

##3.5 Auflistung der Kommentare zu Geodatensätze

Status: Specified

Request:

POST /geodata/<idGeoData:int>/comments/
{
	"q": "<keywords:string>",
	"bbox": "<bbox:wkt>",
	"radius": "<radiusInKm:int>",
	"start": "<start:datetime>",
	"end": "<end:datetime>",
	"minrating": <rating:int>,
	"metadata": <searchInMetadata:boolean>
}

Optional parameters:

q
radius (defaults to BBox area)
start
end
minrating
metadata (default: false)

Response:

When available:

HTTP 1.1 200 OK
{
	"geodata": {
		"id": <id:int>,
		"url": "<url:string>",
		"metadata": {
			"datatype": "<datatype:service>",
			"title": "<title:string>",
			"bbox": "<bbox:wkt>",
			"keywords": ["<keyword1:string>", "<keyword2:string>", ...],
			"beginTime": "<beginTime:datetime>",
			"language": "<language:langcode>",
			"copyright": "<copyright:string>",
			"author": "<author:string>",
			"publisher": "<publisher:string>"
			"endTime": "<endTime:datetime>",
			"abstract": "<abstract:string>",
			"license": "<license:string>"
		},
		"comments": [{
			"id": <id:int>,
			"text": "<text:string>",
			"rating": <rating:int>,
			"geometry": "<geometry:wkt>",
			"time": {
				"start": "<start:datetime>",
				"end": "<end:datetime>"
			},
			"user": {
				"id": <id:int>,
				"name": "<name:string>"
			}
		}, ...],
		"layer": [{
			"id": "<id:string>",
			"title": "<title:string>",
			"bbox": "<bbox:wkt>",
			"comments": [{
				"id": <id:int>,
				"text": "<text:string>",
				"rating": <rating:int>,
				"geometry": "<geometry:wkt>",
				"time": {
					"start": "<start:datetime>",
					"end": "<end:datetime>"
				},
				"user": {
					"id": <id:int>,
					"name": "<name:string>"
				}
			}, ...]
		}, ...]
	}
}

On failure/error:

HTTP 1.1 409 Conflict
{}

#4 Templates and pages (e.g. user guide and imprint)

Status: Specified / Implemented

Request: GET /doc/<page:string>

Page can be one of the following:

about Info page with imprint and other project information.
help User guide
... and all .blade.php-files available in the app/views/pages folder.

Response:

HTTP 1.1 200 OK
Content-Type: text/html; charset=utf-8
<content:html>

#5 Access to the external API

See External API for more information.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Client Server Protocol

1.5.2 Change password (regularily)

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally