.NET Core Webservice API

Dokumentation der .NET Core Webservice API

Version: 1.0.0

Copyright: © 2016 u-werk GbR

Aktualisierungsdatum: 01.10.2016

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

XML ist das Standardausgabeformat der REST-Schnittstelle. Die Schnittstelle antwortet in Content-Type: application/xml; charset=utf-8.

JSON

Eine Antwort in JSON kann für jede Anfrage an die REST-Schnittstelle über den standardisierten HTTP Accept-Header oder alternativ über den HTTP/GET Parameter format und die Wertzuweisung application/json angefordert werden. Geantwortet wird hieraufhin mit 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 HTTP/GET Parameter callback in dem der gewünschte Methodenname eingetragen wird. Beantwortet wird diese Anfrage mit Content-Type: application/javascript; charset=utf-8.

Javascript (CORS)

Neben Cross-Domain HTTP/GET Anfragen mittels JSONP bietet die REST-Schnittstelle Cross-Origin Resource Sharing (CORS) an. Beispiele zur Anwendung von Cross-Domain Anfragen 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.

Der Zugriffsschlüssel zur Verwendung in X-Auth-Token wird bei erfolgreicher Anmeldung des Nutzers übergeben (s.h. Nutzer anmelden). Dieser Zugriffsschlüssel ist für 24 Stunden gültig. Danach ist eine Authentifizierung mit diesem Schlüssel nicht mehr möglich und eine weitere Anmeldung notwendig.

Vorlage: Authentifizierte GET Anfrage HTTP GET XML Mit Authentifizierung
GET /api/v1/todo HTTP/1.1
Host: localhost:5000
X-Auth-Token: pndVpURTRaREkz

Eine authentifizierte Anfrage mittels cURL
Beispiel: Authentifizierte GET Anfrage über Kommandozeile mittels cURL cURL HTTP GET XML Mit Authentifizierung
curl -H "X-Auth-Token: pndVpURTRaREkz" -X GET http://localhost:5000/api/v1/todo

Eine authentifizierte Anfrage in JavaScript mittels jQuery
Beispiel: Authentifizierte GET Anfrage in JavaScript / jQuery jQuery HTTP GET JavaScript (JSONP) Mit Authentifizierung
jQuery.ajax({type: 'GET', url: 'http://localhost:5000/api/v1/todo',
beforeSend: function(xhr, settings) {
   xhr.setRequestHeader('X-Auth-Token', 'pndVpURTRaREkz'); 
}, dataType: 'jsonp', success: function(contents) { … }});

Eine authentifizierte Anfrage in Python mittels urllib2
Beispiel: Authentifizierte GET Anfrage in Python Python HTTP GET XML Mit Authentifizierung
import urllib2
request = urllib2.Request("http://localhost:5000/api/v1/todo", headers={"X-Auth-Token": "pndVpURTRaREkz"})
contents = urllib2.urlopen(request).read()

Eine authentifizierte Anfrage in PHP
Beispiel: Authentifizierte GET Anfrage in PHP PHP HTTP GET XML Mit Authentifizierung
$contents = file_get_contents( 'http://localhost:5000/api/v1/todo', false, stream_context_create( array( 'http' => array(
  'method' => 'GET',
  'header' => Array('X-Auth-Token: pndVpURTRaREkz')
))));

Eine authentifizierte Anfrage in .NET 4.5 mittels System.Net.WebClient
Beispiel: Authentifizierte GET Anfrage in .NET .NET 4.5 HTTP GET XML Mit Authentifizierung
System.Net.WebClient request = new System.Net.WebClient();
request.Headers.Add( "X-Auth-Token", "pndVpURTRaREkz" );
var contents = request.DownloadString( "http://localhost:5000/api/v1/todo" );

Eine authentifizierte Anfrage in .NET Core mittels System.Net.Http
Beispiel: Authentifizierte GET Anfrage in .NET .NET Core HTTP GET XML Mit Authentifizierung
...

REST Web-Services

Zum Nutzer

Anmelden

Schnittstelle: http://localhost:5000/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

Beispiel: Erfolgreiche Login-Anfrage HTTP GET JSON
http://localhost:5000/api/v1/login?format=application/json&loginname=mustermann&password=d68d278ebf67570386e222f79a65bd1a5979f61bf
Antwort
{"resultset":[{"name":"Hans Mustermann","id":3,"token":"pndVpURTRaREkz","loginname":"mustermann"}]}
Beispiel: Erfolgreiche Login-Anfrage beantwortet in XML HTTP GET XML
http://localhost:5000/api/v1/login?loginname=mustermann&password=d68d278ebf67570386e222f79a65bd1a5979f61bf
Antwort
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xml><resultset><row><name>Hans Mustermann</name><id>3</id><token>pndVpURTRaREkz</token><loginname>mustermann</loginname></row></resultset></xml>
Beispiel: Login-Anfrage in JavaScript / jQuery jQuery HTTP GET JavaScript (JSONP)
jQuery.ajax({ statusCode : { 200 : function( data ) { if( data && data.id ) { /* ... Login OK ... */ } else { /* ... Login fehlerhaft ... */ }}}, type: 'GET', url: 'http://localhost:5000/api/v1/login?', data : { loginname: 'mustermann', password: 'd68d278ebf67570386e222f79a65bd1a5979f61bf' }, dataType : 'jsonp', error : function( xmlhttp ){ /* ... Verbindung fehlerhaft ... */ }});

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

Abfragen (der Liste der hinterlegten Todo)

Schnittstelle: http://127.0.0.1:5000/api/v1/todo
Methoden:

optionaler Header (für Authentifizierung): Parameter: Antwort:

Änderungsprotokolle der Web Service API

Keine Einträge vorhanden.

FAQ

Keine Einträge vorhanden.

Impressum

Technische und fachliche Umsetzung

u-werk Umweltinformationsdienste GbR
www.u-werk.net, info@u-werk.net

Copyright © 2016 u-werk Umweltinformationsdienste GbR