Skip to content
This repository was archived by the owner on Feb 22, 2023. It is now read-only.

Client Server Protocol

Jump to bottom
Matthias Mohr edited this page Jan 13, 2015 · 58 revisions

#0 Preface

Version 1.4.0

History of changes

  1. 04.12.2014 14:00 - 1.0.0 - Initial version
  2. 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.
  3. 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 start and end time.
  4. 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.
  5. 12.01.2015 18:00 - 1.4.0 - Standardised start/end time handling; added permalinks, avg ratings und comment requests, added comment ID filter.

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. Also check general validity.
  • name: Checks whether the specified value (user name) is not taken yet. Also check general validity.

Response:

When value is valid / ok:

HTTP 1.1 200 OK
{}

When value is invalid / not ok:

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

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>,
	"datepicker": {
		"format": "<dateFormat>",
	},
	"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 3.1.2)
  • datatype (only optional when URL is already existant, see chapter 3.1.2)

Response:

On success:

See the response in chapter 3.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>",
		"permalink": "<url:string>",
		"isNew": <isNewUrl:boolean>,
		"metadata": {
			"datatype": "<datatype:service>",
			"title": "<title:string>",
			"bbox": "<bbox:wkt>",
			"keywords": ["<keyword1:string>", "<keyword2:string>", ...],
			"language": "<language:langcode>",
			"copyright": "<copyright:string>",
			"author": "<author:string>",
			"abstract": "<abstract:string>",
			"license": "<license:string>",
			"time": {
				"start": "<startTime:datetime>",
				"end": "<endTime:datetime>"
			}
		},
		"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 / Implemented

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>",
		"permalink": "<url:string>",
		"comments": <commentCount:integer>,
		"metadata": {
			"datatype": "<datatype:service>",
			"title": "<title:string>",
			"bbox": "<bbox:wkt>",
			"keywords": ["<keyword1:string>", "<keyword2:string>", ...],
			"language": "<language:langcode>",
			"copyright": "<copyright:string>",
			"author": "<author:string>",
			"abstract": "<abstract:string>",
			"license": "<license:string>",
			"time": {
				"start": "<startTime:datetime>",
				"end": "<endTime:datetime>"
			}
		}
	}, ...]
}

###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 / Implemented

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:

On success:

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

On error:

HTTP 1.1 409 Conflict
{}

####3.4.2 Load permalink

Status: Specified / Implemented

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

Response:

When available:

HTTP 1.1 200 OK
{
	"permalink": {
		"q": "<keywords:string>",
		"bbox": "<bbox:wkt>",
		"radius": "<radiusinKm:int>",
		"minrating": "<rating:int>",
		"metadata": <searchInMetadata:boolean>,
		"time": {
			"start": "<startTime:datetime>",
			"end": "<endTime:datetime>"
		}
	}
}

When not found:

HTTP 1.1 404 Not Found
{}

##3.5 Auflistung der Kommentare zu Geodatensätze

Status: Specified / Implemented

Request:

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

Optional parameters:

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

Response:

When available:

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

Note: For anonymous users the user entry is null.

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.

Clone this wiki locally