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 Allgemeines

##0.1 Versionierung Version 1.0.0

Änderungen:

  1. 04.12.2014 14:00 - 1.0.0 - Initial version

##0.2 Algemeine Definitionen

  • <name:datatype> = Platzhalter mit Namen name und Datentyp datatype
  • Kein Resultat = Es wird ein leeres Array zurückgegeben.

##0.3 Datentypen

  • 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

##0.4 Basis-URL

Basis-URL der API: http://<domain>/api/internal/

#1 Benutzerverwaltung

##1.1 Authentifizierung

Anfrage: siehe Kapitel 1.1.1 - 1.1.3

Antwort:

Bei Erfolg:

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

Im Fehlerfall:

HTTP 1.1 403 Forbidden
{}

###1.1.1 mit MMM-Account

Status: Spezifiziert

Anfrage: GET /auth/login/<kennung:string>/<password:sha1-hash> Kennung = Name oder E-Mail-Adresse

Antwort: siehe Antwort 1

###1.1.2 mit externer Authentifizierung via OAuth

Status: Unspezifiziert

Anfrage: GET /auth/<dienst:string>/<benutzerkennung?>

Antwort: siehe Antwort 1

###1.1.3 mit Session-Hash (Keep-alive)

Status: Spezifiziert

Anfrage: GET /auth/keepalive/<session:string>

Antwort: siehe Antwort 1

###1.1.4 Abmelden

Status: Spezifiziert

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

Antwort:

HTTP 1.1 200 OK
{}

###1.1.5 Passwort zurücksetzen

####1.1.5.1 E-Mail mit Link zum Zurücksetzen des Passworts anfordern

Status: Spezifiziert

Anfrage: GET /auth/remind/request/<email:string>

Antwort:

Bei Erfolg:

HTTP 1.1 200 OK
{}

Im Fehlerfall:

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

####1.1.5.2 Benutzer mit dem temporären Passwort authentifizieren

Status: Spezifiziert

Anfrage: GET /auth/remind/verify/<tempPassword:string>

Antwort:

Bei Erlaubnis:

HTTP 1.1 200 OK
{}

Im Fehlerfall:

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

##1.2 Registrierung

Status: Spezifiziert

Anfrage:

POST /register
name=<name:string>&email=<email:string>&password1=<password1:sha1-hash>&password2=<password2:sha1-hash>

Antwort:

HTTP 1.1 200 OK
{}

##1.3 Daten ändern

###1.3.1 Allgemeine Nutzerdaten ändern

Status: Spezifiziert

Anfrage:

POST /user/change/general
name=<name:string>&email=<email:string>&language=<language:langcode>

Antwort:

Bei Erfolg:

HTTP 1.1 200 OK
{}

Im Fehlerfall:

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

1.3.2 Passwort ändern

Status: Spezifiziert

Anfrage:

POST /user/change/password
old=<password:sha1-hash>&password1=<password1:sha1-hash>&password2=<password2:sha1-hash>

Antwort:

Bei Erfolg:

HTTP 1.1 200 OK
{}

Im Fehlerfall:

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

###1.3.1 Sprache ändern (nur angemeldete Nutzer)

Status: Spezifiziert

Anfrage: GET /user/change/language/<language:langcode>

Antwort:

Bei Erfolg:

HTTP 1.1 200 OK
{}

Im Fehlerfall:

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

##1.4 Daten prüfen

###1.4.1 Benutzername auf Verfügbarkeit prüfen

Status: Spezifiziert

Anfrage: GET /user/check/name/<name:string>

Antwort:

Wenn verfügbar:

HTTP 1.1 200 OK
{}

Wenn vergeben:

HTTP 1.1 409 Conflict
{}

###1.4.2 E-Mail-Adresse auf Existenz prüfen

Status: Spezifiziert

Anfrage: GET /user/check/email/<email:string>

Antwort:

Wenn nicht existent:

HTTP 1.1 200 OK
{}

Wenn existent:

HTTP 1.1 409 Conflict
{}

#2 Sprache

##2.1 Sprachdatei abrufen

Status: Spezifiziert

Anfrage: GET /language/<language:langcode>

Antwort:

Wenn existent:

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

Wenn nicht existent:

HTTP 1.1 404 Not Found
{}

#3 Grundkarten abrufen

Status: Spezifiziert

Anfrage: GET /basemaps

Antwort:

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

#4 Geodatensätze und Kommentare

##4.1 Hinzufügen von Geodatensätzen bzw. Kommentaren

###4.1.1 Daten speichern

Status: Spezifiziert

Anfrage:

POST /geodata/add/^
url=<url:string>&text=<text:string>&geometry=<geometry:wkt>&start=<startTime:datetime>&end=<endTime:datetime>&rating=<rating:int>&uname=<nameAnonymerNutzer:string>&title=<title:string>

Antwort:

Wenn erfolgreich:

siehe Kapitel Rückgabe in Kapitel 4.3 Auflistung der Kommentare zu Geodatensätze.

Wenn fehlerhaft:

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

###4.1.2 Metadaten lesen (Gültigkeit der URL prüfen)

Status: Spezifiziert

Anfrage:

POST /geodata/metadata/
url=<url:string>

Antwort:

Hinweis: Wenn isNew=true ist, muss noch ein Titel vom Nutzer gewählt werden, Vorschlag kommt aus geodata.metadata.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 Auflistung der Geodatensätze (mit Suche/Filter)

###4.2.1 ... mit Raumbezug

Status: Spezifiziert

Anfrage:

POST /geodata/list/
q=<keywords:string>&bbox=<bbox:wkt>&location=<location:wkt>&radius=<radiusInKm:int>&start=<start:datetime>&end=<end:datetime>&minrating=<rating:int>

Hinweis: bbox oder location/radius kann nur exklusiv genutzt werden.

Antwort:

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: Spezifiziert

Anfrage:

POST /geodata/list/junk
q=<keywords:string>&start=<start:datetime>&end=<end:datetime>&minrating=<rating:int>

Antwort:

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 der Suchbegriffe

Status: Spezifiziert

Anfrage: GET /geodata/keywords/<keyword:string>

Antwort:

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

###4.2.4 Permalinks

####4.2.4.1 Permalink speichern

Status: Spezifiziert

Anfrage:

POST /geodata/search/save
q=<keywords:string>&bbox=<bbox:wkt>&location=<location:wkt>&radius=<radiusinKm:int>&start=<start:datetime>&end=<end:datetime>&minrating=<rating:int>

Antwort:

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

####4.2.4.2 Permalink abrufen

Status: Spezifiziert

Anfrage: GET /geodata/search/load/<id:sha1-hash>

Antwort:

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>"
	},
	"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: Spezifiziert

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

Antwort:

Wenn vorhanden:

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

Wenn nicht vorhanden:

HTTP 1.1 409 Conflict
{}

#5 Benutzerhilfe

Status: Spezifiziert

Anfrage: GET /doc/help

Antwort:

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

#6 Informationsseite

Status: Spezifiziert

Anfrage: GET /doc/about

Antwort:

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

#7 Externer API-Zugriff

See External API for more information.

Clone this wiki locally