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
m-mohr edited this page Dec 22, 2014 · 58 revisions

#0 Preface

Version 1.1.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.

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 algorithms (hasing algorithm: TBD).
  • wkt = Well Known Text - Geo data type, e.g. POINT(0 180)
  • datetime = Date and time (format: TBD)
  • html = HTML source code

Base URL

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

#1 User management

##1.1 Authentification / Log in

Status: Partially specified (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

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

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

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

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

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

1.5.2 Change password (regularily)

Status: Specified

Request:

POST /user/change/password
{
	"old": "<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>",
	...
}

##1.6 Check user data

Status: Specified

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

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 translatrion

Status: Specified

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

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

Request:

POST /geodata/add/
{
	"url": "<url: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
  • title (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 Rad metadata (check validity of URL)

Status: Specified

Request:

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

Response:

*Node: 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:string>",
			"title": "<title:string>",
			"bbox": "<bbox:wkt>",
			"subject": "<subject:string>",
			"creation": "<creationTime:datetime>",
			"language": "<language:langcode>",
			"copyright": "<copyright:string>",
			"author": "<author:string>",
			"publisher": "<publisher:string>",
			"modified": "<modified:datetime>",
			"abstract": "<abstract:string>"
		},
		"layer": [{
			"id": "<id:string>",
			"title": "<title:string>",
			"bbox": "<bbox:wkt>"
		}, ...]
	}
}

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

###4.2.1 ... with spatial reference

Status: Specified

Request by bounding box:

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

Request by location and radius:

POST /geodata/list/
{
	"q": "<keywords:string>",
	"location": "<location: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.

Note: bbox and location/radius can't be used together.

Optional parameters:

  • q
  • radius (default: 10)
  • start
  • end
  • minrating
  • metadata (default: false)

Response:

HTTP 1.1 200 OK
{
	"geodata": {[
		"id": <id:int>,
		"url": "<url:string>",
		"metadata": {
		"datatype": "<datatype:string>",
			"title": "<title:string>",
			"bbox": "<bbox:wkt>",
			"subject": "<subject:string>",
			"creation": "<creationTime:datetime>",
			"language": "<language:langcode>",
			"copyright": "<copyright:string>",
			"author": "<author:string>",
			"publisher": "<publisher:string>",
			"modified": "<modified:datetime>",
			"abstract": "<abstract:string>"
		},
		"layer": [{
			"id": "<id:string>",
			"title": "<title:string>",
			"bbox": "<bbox:wkt>"
		}, ...]
	], ...}
}

###4.2.2 ... ohne Raumbezug

Status: Specified

Request:

POST /geodata/list/junk
{
	"q": "<keywords:string>",
	"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
  • start
  • end
  • minrating
  • metadata (default: false)

Response:

HTTP 1.1 200 OK
{
	"geodata_junk": [{
		"id": <id:int>,
		"url": "<url:string>",
		"metadata": {
			"datatype": "<datatype:string>",
			"title": "<title:string>",
			"bbox": "",
			"subject": "<subject:string>",
			"creation": "<creationTime:datetime>",
			"language": "<language:langcode>",
			"copyright": "<copyright:string>",
			"author": "<author:string>",
			"publisher": "<publisher:string>",
			"modified": "<modified:datetime>",
			"abstract": "<abstract:string>"
		},
		"layer": [{
			"id": "<id:string>",
			"title": "<title:string>",
			"bbox": ""
		}, ...]
	}, ...]
}

###4.2.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.2.4 Permanent links for search results

####4.2.4.1 Save permalink

Status: Specified

Request by bounding box:

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

Request by location and radius:

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

Note: bbox and location/radius can't be used together.

Optional parameters:

  • q
  • radius (default: 10)
  • start
  • end
  • minrating
  • metadata (default: false)

Response:

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

####4.2.4.2 Load permalink

Status: Specified

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

Response:

Note: Either bbox or location/radius will be included in the reponse, but never both together.

HTTP 1.1 200 OK
{
	"permalink": {
		"q": "<keywords:string>",
		"bbox": "<bbox:wkt>",
		"location": "<location: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:string>",
			"title": "<title:string>",
			"bbox": "<bbox:wkt>",
			"subject": "<subject:string>",
			"creation": "<creationTime:datetime>",
			"language": "<language:langcode>",
			"copyright": "<copyright:string>",
			"author": "<author:string>",
			"publisher": "<publisher:string>",
			"modified": "<modified:datetime>",
			"abstract": "<abstract:string>"
		},
		"layer": [{
			"id": "<id:string>",
			"title": "<title:string>",
			"bbox": "<bbox:wkt>"
		}, ...]
	], ...},
	"geodata_junk": {[
		"id": <id:int>,
		"url": "<url:string>",
		"metadata": {
		"datatype": "<datatype:string>",
			"title": "<title:string>",
			"bbox": "",
			"subject": "<subject:string>",
			"creation": "<creationTime:datetime>",
			"language": "<language:langcode>",
			"copyright": "<copyright:string>",
			"author": "<author:string>",
			"publisher": "<publisher:string>",
			"modified": "<modified:datetime>",
			"abstract": "<abstract:string>"
		},
		"layer": [{
			"id": "<id:string>",
			"title": "<title:string>",
			"bbox": ""
		}, ...]
	], ...}
}

##4.3 Auflistung der Kommentare zu Geodatensätze

Status: Specified

Request: GET /geodata/<idGeoData:int>/comments/

Response:

When available:

HTTP 1.1 200 OK
{
	"geodata": {
		"id": <id:int>,
		"url": "<url:string>",
		"metadata": {
			"datatype": "<datatype:string>",
			"title": "<title:string>",
			"bbox": "<bbox:wkt>",
			"subject": "<subject:string>",
			"creation": "<creationTime:datetime>",
			"language": "<language:langcode>",
			"copyright": "<copyright:string>",
			"author": "<author:string>",
			"publisher": "<publisher:string>"
			"modified": "<modified:datetime>",
			"abstract": "<abstract: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>"
		},
		"fitToFilter": <fit:boolean>,
		"user": {
			"id": <id:int>,
			"name": "<name:string>",
			"email": "<email:string>",
			"language": "<language:langcode>"
		}
	}, ...]
}

On failure/error:

HTTP 1.1 409 Conflict
{}

#5 User guide

Status: Specified

Request: GET /doc/help

Response:

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

#6 Info page / Imprint

Status: Specified

Request: GET /doc/about

Response:

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

#7 Access to the external API

See External API for more information.

Clone this wiki locally