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 7, 2015 · 58 revisions

#0 Preface

Version 1.2.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 requests to JSON format, changed auth and user management requests and responses, added metadata search filter, avoid session keys if possible, changed password reset api, return documents as html only, added data types, bugfixes.
  3. 26.12.2014 17:00 - 1.1.1 - Specified date/time format, added possibility to select a layer and a datatype for the metadata URLs
  4. 05.01.2015 20:00 - 1.1.2 - Datatype of URLs has to be specified. Removed automatic detection capabilities.
  5. 06.01.2015 15:00 - 1.2.0 - Removed junk request. Added filter operations for comments. Merged location/radius and bbox based filter. Changed modified and creation time from geodata to begin and end time.

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 data is valid / ok:

HTTP 1.1 200 OK
{}

When data is invalid / not ok:

HTTP 1.1 409 Conflict
{}

##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 Language

##2.1 Request language file with phrases for translation

Status: Specified / Implemented

Request: GET /language/<language:langcode>

Response:

On success:

HTTP 1.1 200 OK
{
	"language": "<langcode:langcode>",
	"phrases": {
		"<key:string>": "<key:value>",
		...
	}
}

On failure/error:

HTTP 1.1 404 Not Found
{}

#3 Request list of active basemaps

Status: Specified / Implemented

Request: GET /basemaps

Response:

HTTP 1.1 200 OK
{
	"basemaps": [{
		"url": "<url:string>",
		"name": "<name:string>"
	}, ...]
}

#4 Geo data sets and comments

##4.1 Adding geodata and comments

###4.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.3.

On failure/error:

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

###4.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>"
}

###4.1.3 Read list of supported metadata formats

Status: Specified / Implemented

Request: GET /geodata/formats

Response:

HTTP 1.1 200 OK
{
	"formats": [{
		"code": "<datatype:service>",
		"name": "<name:string>"
	}, ...]
}

##4.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>",
		"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>"
		}, ...]
	}, ...]
}

###4.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>", ...]
}

###4.4 Permanent links for search results

####4.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>"
}

####4.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>",
		"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>"
		}, ...]
	}, ...]
}

##4.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>"
		},
		"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>",
			"email": "<email:string>",
			"language": "<language:langcode>"
		}
	}, ...]
}

On failure/error:

HTTP 1.1 409 Conflict
{}

#5 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>

#6 Access to the external API

See External API for more information.

Clone this wiki locally