External API

This document is currently only available in German. Sorry for any inconvenience.

Eine gemeinsame API Spezifikation für einfache Suche und Encoding der Suchergebnisse ist in diesem Abschnitt spezifiziert. Alle Anfragen basieren auf HTTP GET.

Basis URL der API

• ApiBase = “http://” + [server:port] + “/api”
• Versionsnummer = ApiBase + / + Versionsnummer

Basis URL (BaseURL) der ersten Version: http://[server:port]/api/v1/

Suche von Kommentaren

Die API für Suche baut auf der OpenSearch - Spezifikation und ihrer Erweiterungen auf http://www.opensearch.org.

Eine Nutzung der OpenSearch API für weiterführende Funktionalität wird empfohlen. Im folgenden wird jedoch nur eine einfache Suche mit Parameter spezifiziert um eine grundlegende Interoperabilität zwischen verschiedenen Lösungen der AN zu gewährleisten.

Suchbegriff und Ergebnisanzahl

Die folgenden Parameter sollen für eine einfache Kommentarsuche implementiert werden.

• Endpoint für Suche: BaseURL + “search”
• URL Parameter für Suchbegriff: q
• Optionaler URL Parameter für Anzahl der Suchergebnisse: count

Wenn der count-Parameter nicht gegeben ist werden alle verfügbaren Ergebnisse vom Server zurück gegeben. Eine Server-seitige Limitierung ist möglich aber muss dem client nicht kommuniziert werden.

• Such-URL: http://[server:port]/api/v1/search?q=Fluss
• Such-URL mit maximal 42 Ergebnissen: http://[server:port]/api/v1/search?q={Suchbegriff}&count=42

Antwortdokument

Das Antwortdokument entspricht folgendem Schema und ist im UTF-8 - Format encodiert. Der content type ist application/json. Die korrekten HTTP Status Codes werden zur Kommunikation von Fehlern genutzt.

Beispieldokument

{
	"resource": "http://link-to-the.resource/of?thisdocument",
	"itemUnderReview": "http://url.to.dataset?that_is/available&online",
	"comments": [
		{
			"id": "http://geocomment.com/comment/100",
			"text": "This is the user-generated comment text"
		},
		{
			"id": "http://geocomment.com/comment/200",
			"text": "This is another comment text",
			"rating": 4
		}
	]
}

JSON Schema

{
	"type": "object",
	"$schema": "http://json-schema.org/draft-03/schema",
	"id": "http://jsonschema.net",
	"required": false,
	"properties": {
		"comments": {
			"type": "array",
			"minitems": "0",
			"id": "http://jsonschema.net/comments",
			"required": true,
			"items":
					{
						"type": "object",
						"id": "http://jsonschema.net/comments/1",
						"required": false,
						"properties": {
							"id": {
								"type": "string",
								"id": "http://jsonschema.net/comments/1/id",
								"required": false
							},
							"rating": {
								"type": "integer",
								"id": "http://jsonschema.net/comments/1/rating",
								"required": false
							},
							"text": {
								"type": "string",
								"id": "http://jsonschema.net/comments/1/text",
								"required": true
							}
						}
					}


		},
		"itemUnderReview": {
			"type": "string",
			"id": "http://jsonschema.net/itemUnderReview",
			"required": true
		},
		"resource": {
			"type": "string",
			"id": "http://jsonschema.net/resource",
			"required": true
		}
	}
}