Mediathek Web Service API

Dokumentation der Mediathek REST Web-Service API

Version: 1.0.10

Copyright: © 2014 LANUV NRW

Aktualisierungsdatum: 01.06.2022

Verzeichnis

Allgemeines

Zeichenkodierung

Die REST-Schnittstelle antwortet in der Kodierung UTF-8.

Formate

Die REST-Schnittstelle beantwortet Anfragen in den Formaten XML, JSON oder JavaScript.

XML

Eine Antwort in XML kann für jede Anfrage an die REST-Schnittstelle über den URL-Parameter format und die Wertzuweisung xml angefordert werden. Geantwortet wird hieraufhin mit Content-Type: text/xml; charset=utf-8.

JSON

JSON ist das Standardausgabeformat der REST-Schnittstelle. Standardgemäss antwortet die Schnittstelle in Content-Type: application/json; charset=utf-8.

JavaScript

Die REST-Schnittstelle gibt für in JSON with padding (JSONP) angeforderte Antworten JavaScript zurück. Die Anforderung erfolgt über den URL-Parameter callback in dem der gewünschte Methodenname eingetragen wird. Beantwortet wird diese Anfrage mit Content-Type: application/javascript; charset=utf-8.

Neben Cross-Domain GET-Anfragen mittels JSONP bietet die REST-Schnittstelle für Schreiboperationen in JavaScript für die Methoden POST, PUT und DELETE Cross-Origin Resource Sharing (CORS) an. Beispiele zur Anwendung von Cross-Domain Schreiboperationen in JavaScript sind detailliert im jeweiligen Abschnitt dokumentiert.

Authentifizierung für zugriffsbeschränkte Anfragen

Die Nutzer-Authentisierung der REST-Schnittstelle erfolgt einheitlich für die Methoden GET, POST, PUT und DELETE. Zusätzlich zur jeweiligen Anfrage ist hierfür der Header X-Auth-Token erforderlich, Platzhalter für den Zugriffsschlüssel des Nutzers.

Der Zugriffsschlüssel zur Verwendung in X-Auth-Token wird bei erfolgreicher Anmeldung des Nutzers übergeben (s. Nutzer anmelden).

Vorlage: Authentifizierte GET Anfrage HTTP GET JSON Mit Authentifizierung
GET /mediathek/api/v1/assets HTTP/1.1
    Host: mediathek.naturschutzinformationen.nrw.de 
    X-Auth-Token: pndVpURTRaREkz

Eine authentifizierte Anfrage mittels cURL
Beispiel: Authentifizierte GET Anfrage über Kommandozeile mittels cURL cURL HTTP GET JSON Mit Authentifizierung
curl -H "X-Auth-Token: pndVpURTRaREkz" -X GET https://mediathek.naturschutzinformationen.nrw.de/mediathek/api/v1/assets

Eine authentifizierte Anfrage in JavaScript
Beispiel: Authentifizierte GET Anfrage in JavaScript / jQuery jQuery HTTP GET JavaScript (JSONP) Mit Authentifizierung
jQuery.ajax({type: 'GET', url: 'https://mediathek.naturschutzinformationen.nrw.de/mediathek/api/v1/assets',
    beforeSend: function(xhr, settings) { 
       xhr.setRequestHeader('X-Auth-Token', 'pndVpURTRaREkz'); 
    }, dataType: 'jsonp', success: function(contents) { … }});

Eine authentifizierte Anfrage in Python
Beispiel: Authentifizierte GET Anfrage in Python Python HTTP GET JSON Mit Authentifizierung
import urllib2
    request = urllib2.Request("https://mediathek.naturschutzinformationen.nrw.de/mediathek/api/v1/assets", headers={"X-Auth-Token": "pndVpURTRaREkz"})
    contents = urllib2.urlopen(request).read()

Eine authentifizierte Anfrage in PHP
Beispiel: Authentifizierte GET Anfrage in PHP PHP HTTP GET JSON Mit Authentifizierung
$contents = file_get_contents( 'https://mediathek.naturschutzinformationen.nrw.de/mediathek/api/v1/assets', false, stream_context_create( array( 'http' => array(
      'method' => 'GET',
      'header' => Array('X-Auth-Token: pndVpURTRaREkz')
    ))));

Eine authentifizierte Anfrage in ASP.NET
Beispiel: Authentifizierte GET Anfrage in ASP.NET ASP.NET HTTP GET JSON Mit Authentifizierung
System.Net.WebClient request = new System.Net.WebClient();
    request.Headers.Add( "X-Auth-Token", "pndVpURTRaREkz" );
    var contents = request.DownloadString( "https://mediathek.naturschutzinformationen.nrw.de/mediathek/api/v1/assets" );

REST Web-Services

Zum Nutzer

Anmelden

Schnittstelle: https://mediathek.naturschutzinformationen.nrw.de/mediathek/api/v1/login
Methoden:

Parameter: Antwort (bei erfolgreicher Anmeldung): Antwort (bei falscher Anmeldung): Leere Antwort mit HTTP/1.1 200 OK
Antwort (bei fehlenden Parametern): Hinweisende Antwort mit HTTP/1.1 400 Bad Request

Login-Anfrage mittels cURL
Beispiel: Login-Anfrage mittels cURL cURL HTTP POST
curl -H "Content-Type: multipart/form-data; charset=utf-8" -F "login=mustermann" -F "password=d68d278ebf67570386e222f79a65bd1a5979f61bf" -X POST https://mediathek.api.naturschutzinformationen.nrw.de/mediathek/api/v1/login
Antwort
{"name":"Hans Mustermann","id":3,"token":"pndVpURTRaREkz","login":"mustermann"}
Login-Anfrage in JavaScript (CORS)
Beispiel: Login-Anfrage in JavaScript / jQuery mittels Cross-Domain / Cross-Origin Resource Sharing (CORS) JavaScript (CORS) HTTP POST 
var data = new FormData();
data.append( 'login', 'mustermann' );
data.append( 'password', 'd68d278ebf67570386e222f79a65bd1a5979f61bf' );
jQuery.ajax({type: 'POST', crossDomain: true, url: 'https://mediathek.api.naturschutzinformationen.nrw.de/mediathek/api/v1/login', cache: false, contentType: false, processData: false, data: data, dataType: 'json', success: function(contents) { … }});

Zur geforderten Kodierung eines Passwortes in SHA-256 mittels JavaScript bieten sich die "JavaScript implementations of standard and secure cryptographic algorithms" an. (Linkverweis: https://code.google.com/p/crypto-js/)

Medien

Anlegen (Aufnahme neuer Medien, z.B. Foto)

Schnittstelle: https://mediathek.api.naturschutzinformationen.nrw.de/mediathek/api/v1/assets

Internet Media Type (MIME-Type)

Für folgende Dateitypen besteht bisher Unterstützung zur Aufnahme in die Mediathek:

Exchangeable Image File Format (Exif)

Folgende Metadaten werden aus Bilddateien bei der Übermittlung automatisiert ausgelesen und indiziert:

Externe Medien (Optional)

Neben der standardgemäßen Übermittlung und Aufnahme von Medien per Dateiupload erlaubt der Webservice optional auch die Einbindung und Verwaltung von weiterhin extern gehaltenen Medien. Hierfür wird dem Pflichtdatenfeld asset nicht die Datei sondern die URL der aufzunehmenden Mediendatei übergeben.

Methoden:

Header (für Authentifizierung): Datenfelder:

Beispiel: Direkter Medienaufruf / Redirect von Medien HTTP GET Ohne Authentifizierung
https://mediathek.api.naturschutzinformationen.nrw.de/mediathek/api/v1/files/fa9625010d639db7b6aeefc664b17334baec3ecb Link
Beispiel: Direkter Medienaufruf / Redirect von Thumbnails HTTP GET Ohne Authentifizierung
https://mediathek.api.naturschutzinformationen.nrw.de/mediathek/api/v1/files/fa9625010d639db7b6aeefc664b17334baec3ecb?type=thumbnail Link
Beispiel: Direkte Einbettung / Redirect in HTML Image Tag HTTP GET Ohne Authentifizierung
<img src="https://mediathek.api.naturschutzinformationen.nrw.de/mediathek/api/v1/files/fa9625010d639db7b6aeefc664b17334baec3ecb" />
<img src="https://mediathek.api.naturschutzinformationen.nrw.de/mediathek/api/v1/files/fa9625010d639db7b6aeefc664b17334baec3ecb?type=thumbnail" />

Löschen (von Medien)

Schnittstelle: https://mediathek.api.naturschutzinformationen.nrw.de/mediathek/api/v1/assets/:id

Methoden:

Header (für Authentifizierung): optionale Parameter Antwort (bei erfolgreicher Löschung): HTTP/1.1 200 OK
Antwort (bei unberechtigter Anfrage oder nicht vorhandenem Medium): HTTP/1.1 403 Forbidden

Vorlage: DELETE Anfrage HTTP DELETE Mit Authentifizierung 
DELETE /mediathek/api/v1/assets/a12ajksl3jk3jkn4h3jknjk3j4325627e HTTP/1.1
Host: mediathek.api.naturschutzinformationen.nrw.de
X-Auth-Token: pndVpURTRaREkz

Einige Umgebungen unterstützen u.U. die HTTP Methode DELETE nicht, oder die Umsetzung ist schwierig. Hierfür erlaubt der Webservice Methoden im Header zu überladen. Verwenden Sie in einem solchen Fall die Methode POST und übergeben im Header in X-HTTP-Method-Override die gewünschte Methode DELETE.

Vorlage: DELETE Anfrage über POST senden HTTP DELETE (OVERRIDING POST) Mit Authentifizierung 
POST /mediathek/api/v1/assets/a12ajksl3jk3jkn4h3jknjk3j4325627e HTTP/1.1
Host: mediathek.api.naturschutzinformationen.nrw.de 
X-Auth-Token: pndVpURTRaREkz
X-HTTP-Method-Override: DELETE
Löschen eines Medieninhaltes mittels cURL
Beispiel: Entfernung eines Medieninhaltes in der Kommandozeile mittels cURL cURL HTTP DELETE Mit Authentifizierung
curl -i -H 'X-Auth-Token: TVRjeU5qQXpNR014TkRVeFpqWXhZVGd3TldZeVpUQmlaalJpTkRZd05USmpZbU69' -X DELETE https://mediathek.api.naturschutzinformationen.nrw.de/mediathek/api/v1/assets/a12ajksl3jk3jkn4h3jknjk3j4325627e
Löschen eines Medieninhaltes in JavaScript
Beispiel: Löschen eines Medieninhaltes in JavaScript / jQuery mittels Methodenüberladung im Header und Cross-Domain / Cross-Origin Resource Sharing (CORS) JavaScript (CORS) HTTP DELETE (OVERRIDING POST) Mit Authentifizierung 
jQuery.ajax({type: 'POST', crossDomain: true, url: 'https://mediathek.api.naturschutzinformationen.nrw.de/mediathek/api/v1/assets/a12ajksl3jk3jkn4h3jknjk3j4325627e', cache: false, contentType: false, processData: false, data: {},
beforeSend: function(xhr, settings) { 
  xhr.setRequestHeader('X-Auth-Token', 'pndVpURTRaREkz'); 
  xhr.setRequestHeader('X-HTTP-Method-Override', 'DELETE');
}, dataType: 'json', success: function(contents) { … }});

Änderungsprotokolle der Web Service API

Keine Einträge vorhanden.

FAQ

Keine Einträge vorhanden.

Impressum

Anbieter

Landesamt für Natur, Umwelt und Verbraucherschutz Nordrhein-Westfalen
Leibnizstr. 10
45659 Recklinghausen

Telefon: +49 (0)2361 305-0
Telefax: +49 (0)2361 305-3215
e-mail: poststelle@lanuv.nrw.de
Internet: www.lanuv.nrw.de

Technische und fachliche Umsetzung

u-werk, Umweltinformationsdienste
www.u-werk.net, info(at)u-werk.net

Copyright © 2014 LANUV NRW