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

#0 Preface

Version 1.1.0

History of changes

  1. 04.12.2014 14:00 - 1.0.0 - Initial version
  2. 19.12.2014 18:00 - 1.1.0 - Changed POST requests to JSON format, changed user management requests and responses, added metadata search filter, 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.

Data types

  • string = Beliebige Zeichenkette
  • boolean = Wahrheitswert, true oder false
  • int = Ganzzahliger Wert, z.B. 123
  • langcode = Sprachkürzel nach ISO 639-1 Norm, bspw. de, en oder nl
  • sha1-hash = 32 Zeichen lange Zeichenkette aus Buchstaben und Ziffern, gehasht mit der SHA1-Funktion.
  • wkt = Well Known Text - Geo data type, z.B. POINT(0 180)
  • datetime = Datum/Zeit, in einem noch zu spezifizierenden Format
  • html = HTML-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
  • session - Session hash

Request for mmm method:

POST auth/login/mmm
{
    "credentials": {
        "identifier": "<identifier:string>",
        "password": "<password:sha1-hash>"
    }
}

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

Request for oauth method (unspecified as of yet):

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

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

Request for session method:

POST auth/login/session
{
    "credentials": {
        "session": "<session-key:sha1-hash>"
    }
}

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:string>",
		"lastActivity": "<timestamp:int>"
	}
}

On failure/error:

HTTP 1.1 403 Forbidden
{}

###1.2 Log out

Status: Specified

Request: GET /auth/logout/<session:string>

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 /auth/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 Authenticate user with temporary access token to reset the password

Status: Specified

Request: GET /auth/remind/verify/<token:string>

Response:

On success:

HTTP 1.1 200 OK
{}

On failure/error:

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

##1.4 Registration

Status: Specified

Request:

POST /auth/register
{
	"name": "<name:string>",
	"email": "<email:string>",
	"password1": "<password1:sha1-hash>",
	"password2": "<password2:sha1-hash>"
}

Response:

HTTP 1.1 200 OK
{}

##1.3 Change user data

###1.3.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.3.2 Change password (regularily)

Status: Specified

Request:

POST /user/change/password
{
	"old": "<old_password:sha1-hash>",
	"password1": "<new_password1:sha1-hash>",
	"password2": "<new_password2:sha1-hash>"
}

Response:

On success:

HTTP 1.1 200 OK
{}

On failure/error:

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

##1.4 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
{}

#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 aditionally 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 aditionally 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 aditionally 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:sha1-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
{
	"title": "<title:string>",
	"content": "<content:html>"
}

#6 Info page / Imprint

Status: Specified

Request: GET /doc/about

Response:

HTTP 1.1 200 OK
{
	"title": "<title:string>",
	"content": "<content:html>"
}

#7 Access to the external API

See External API for more information.

Clone this wiki locally