DB Rent GmbH. Schnittstellenbeschreibung. Flinkster API NG. Deutsche Bahn Connect GmbH

Transkript

1 DB Rent GmbH Flinkster API NG Schnittstellenbeschreibung Deutsche Bahn Connect GmbH Frankfurt am Main,

2 APING - V1 Inhalt Inhalt Changelog 1 Allgemein 1.1 Technik 1.2 URL Syntax und Versionen 1.3 Base URL 1.4 Encoding 1.5 Sicherheit 1.6 Implementierungshinweise 1.7 Synchrone Antwort 1.8 Mögliche HTTP Response Codes 1.9 Fehler 1.10 Basistypen GeoJson Beschreibung Referenz Collection Beschreibung Struktur Ausnahmebehandlung Attributes 1.11 Parameterdefintion 1.12 Expands 2 Ressourcen 2.1 Index Dienst Response 2.2 Bookingproposals (Buchungsvorschläge) Best-Practice 2.3 ProviderNetwork Subresource: RentalObject (Mietbare Objekte) Subresource Categories Lesen einer Category Auflistung aller Categories Subresource: Prices 2.4 Area (Gebiete) Lesen eines Areals Suche nach Arealen 2.5 Provider Lesen eines Providers Changelog Changelog Version Wann Wer Was Erstveröffentlichung an Kunden am Sebastian Huge Initiale Version Interne Änderungsversion: v Unbekannter Benutzer (andreas.post@dbfuhrpark.com) Bärbel Dußler Unbekannter Benutzer (andreas.post@dbfuhrpark.com) Verfeinerung der ersten Request Methoden Collection-Objekt dokumentiert Ergänzung Suche nach Areas Review aus HAL API V4 mach API V1 noch nicht als Ressource verfügbare Elemente aus Beispielen entfernt Interne Änderungsversion: v Florian Richter Beschreibung der wichtigsten Attribute hinzugefügt.

3 Jens Zeidler Authentifizierung überarbeiten interne Änderungsversion: v Sebastian Huge Diverse Überarbeitungen HTTP Response Codes Entfernen Query Parameter "Attributes" Vorläufiges entfernen Preise im BookingProposal Sebastian Huge Erläuterung Expand Feature interne Änderungsversion: v Michael Czygan Formatierungänderungen kleinere Korrekturen Bärbel Dußler kleine Korrekturen Florian Richter Beispielwerte für category Parameter attributes, expands in Area entfernt Beschreibung rentalinformation, begin und end hinzugefügt Unbekannter Benutzer Beschreibung Mockdaten BookingProposals für Areas dokumentiert. JSON Beispiele aktualisiert Category ergänzt Area unter BookingProposals ergänzt interne Änderungsversion: v Sebastian Huge Erweiterung Area um Provider Key Value Liste in Areas, für zusätzliche Informationen (Stellplätze) Sebastian Huge Definition Links für Appstores/ Apps in Rentalobjects Authentifizierung und Authorisierung auf eigene Seite verschoben ( Authentifizierung und Autorisierung) Bookingproposal: Filter auf Provider und ProviderNetwork RentalObject: Provider für RentalObject RentalObject: intital, URIs für Apps in _links Element Category: Preisinformationen Areas, RentalObject: Dokumentation Attributes Erklärung Attributes Sebastian Huge Bookingproposal: Einfügen Area in Bookingproposal Element Bookingproposal: Durch einen Fehler fehlte das Position Element. Es wurde wieder hinzugefügt. Category: Korrektur grossamount (Double) Category: Beschreibung mögliche Werte für Price Type Category: Ersetzung von clocking durch interval Category: Currency wurde hinzugefügt Rentalobject: Beschreibung möglicher Fuel-Werte Florian Richter Rentalobject: Korrektur und Vervollständigung der aktuell bekannten Fuel-Werte interne Änderungsversion: v interne Änderungsversion: v interne Änderungsversion: v Sebastian Huge Area: Geometry, Position wird nun unterhalb des Elements Geometry gespeichert. Zusätzlich existiert innerhalb Geometry ein centroid, welches einen Mittelpunkt anzeigt, wenn es sich bei der Position um eine Fläche handelt. Basistypen: Geometry durch GeoJson ersetzt, inklusive genauer Erläuterung Maximum Suchradius festgelegt Michael Czygan Aktualisierung Response Beispiele Korrektur area/type, area/attributes mögliche Werte Minimum Suchradius festgelegt bei areas und bookingproposals Aktualisierung und Verschiebung der Applinks: von rentalobjects zu bookingproposals Installlinks in der Liste, Durchbuchungslinks in der spezifischen BookingProposal Sebastian Huge Überarbeitung: 1.8 Fehler ProviderNetworks als neue Resource RentalObjects als Subresource von ProviderNetworks Categories als Subresource von ProviderNetworks Prices als Subresource von Categories Aktualisierung des Applinks interne Änderungsversion: v.147

4 Sebastian Huge Filter ProviderNetwork -> providernetwork Fehlermeldung Attributes kleine Korrektur Michael Czygan AppLinks Bedingung aktualisiert Limit bei bookingproposal, area von 100 auf 50 gesetzt Area/type Beschreibung erweitert Sebastian Huge Anpassung BookingProposal Expands & Response Beispiel Categories Requestparameter ergänzt Kapitel Mockdaten entfernt interne Änderungsversion: v Michael Czygan Vehicle/type, den Typ VehiclePool ergänzt interne Änderungsversion v Michael Czygan neues Vermietmodell (rentalmodel) freefloatingwithstation Erweiterung Preisstruktur, um das Attribut preferredprice interne Änderungsversion v Philipp Ahlner Änderung der Subresource "price" Philipp Ahlner Fehlercodes ergänzt interne Änderungsversion v Florian Richter Beschreibungen detailiert, Infos zur Sicherheit hinzugefügt interne Änderungsversion v Michael Czygan Erweiterung Verfahrensbeschreibung bei der Handhabung von Pagination bei den Rückgabe-Collections: Collections/Fehlerbehandlung hinzugefügt BookingProposals Reponse Behandlung erweitert BookingProposals Limit Parameter Minimum=1 ergänzt Hinweistext zur Ergebnismenge hinzugefügt Best Practice-Anleitung hinzugefügt interne Änderungsversion v.6 1 Allgemein Die Flinkster API NG stellt eine Beauskunftungsschnittstelle von Mobilitätsdienstleistungen der Flinkster Plattform zur Verfügung. Sie ermöglicht die Suche nach Mietstandorten und verfügbaren Mietobjekten bspw. für Angebote aus dem Car- und Bikesharing. 1.1 Technik Die API basiert auf REST und verwendet für die Aufrufe die HTTP Standard-Verben. Alle Antworten erfolgen als JSON. 1.2 URL Syntax und Versionen Die Request-URLs am Server sind wie folgt aufgebaut URL Syntax Die URL Abschnitte vor dem Pfad methode sind in dieser Dokumentation unter der Adresse zur besseren Lesbarkeit zusammengefasst.

5 GET: Beispiel 1.3 Base URL Alle URLs in dieser Schnittstellenspezifikation beginnen mit der folgenden Base URL: Base URL 1.4 Encoding Sonderzeichen in URIs müssen URL-encodiert werden. In der folgenden Dokumentation sind sie daher wegen besserer Lesbarkeit nicht enthalten. Beispiel: nd= t15%3a00%3a00%2b01%3a00 wird in der Dokumentation wie folgt dargestellt: Sicherheit Zur Nutzung der Ressourcen der Flinkster API NG wird bei jedem Aufruf ein gültiges OAuth2 Token benötigt. Diese kann man sich mit Hilfe der zur Verfügung gestellten Zugangsdaten durch den bereitgestellten OAuth2 Service der Deutsche Bahn Connect GmbH erzeugen und validieren lassen. Weitere Informationen finden sie in dem Dokument "Nutzung_der_Flinkster_Customer_API_mit_Private_Key_Verfahren_JWT_Bearer_Token". 1.6 Implementierungshinweise Der Aufrufer der Schnittstelle muss sicherstellen, dass er mit zusätzlichen Attributen in den Antworten umgehen kann. 1.7 Synchrone Antwort Alle Antworten der Schnittstelle erfolgen per Default synchron. Sie enthält als direkte Antwort einen HTTP Response 200 und die gewünschte Antwort. 1.8 Mögliche HTTP Response Codes HTTP Statuscode Beschreibung 200 OK Der Request war erfolgreich und der Body enthält die angeforderten Informationen.

6 400 Bad Request Die Anfrage ist nicht korrekt und kann daher nicht beantwortet werden. Im Body sind weitere Informationen zum Fehler enthalten. 401 Not Authorized Authentifizierung ungültig oder abgelaufen 403 Forbidden Zugriff auf diese Ressource nicht erlaubt. 404 Not Found Die Ressource konnte nicht gefunden werden. 500 Internal Server Error Der Anwendung lief in einen unerwarteten Fehler 501 Not Implemented Der Request wird nicht unterstützt 502 Bad Gateway Der Request konnte nicht weitergeleitet werden Zusätzlich können weitere HTTP Statuscodes gemäß der HTTP Statuscode Spezifikation zurückgeliefert werden: /rfc2616-sec10.html 1.9 Fehler Die REST API antwortet auf Error oder Warning mit einem entsprechenden HTTP Response Code (z. B. 400, 403). Zusätzlich liefert der Response Body weitere Informationen. Attribut Beschreibung Typ code API spezifischer Fehler Code Integer level Fehlerklassifizierung, mögliche Werte: ERROR WARNING String name Name der Fehlermeldung String message Kurze, verständliche Nachricht für den Endnutzer String attributes Information über den fehlerhaften Anfrageparameter: Object Error Code (API) Attribut Beschreibung Typ 2 contraintelementvalue Wie lautet der fehlerhafte Wert String 2 contraintelementname In welchem Query Parameter wurde der fehlerhafte Wert benutzt String Code 1 enthält keine Attributes

7 HTTP/ Bad Request Error "errors": "code":2, "level":"error", "name":"constraintvalidation", "message":"muss zwischen -90 und 90 liegen", "attributes": "constraintelementvalue":" ", "constraintelementname":"lat" "code":2, "level":"error", "name":"constraintvalidation", "message":"muss zwischen 100 und liegen", "attributes": "constraintelementvalue":"20000", "constraintelementname":"radius" HTTP-Code Code Level Name Beschreibung Error UnknownError Unbekannter Fehler Error ConstraintValidation Validierungsfehler von Eingabeparameter (z.b. von Pfad-, Formularparameter) Error ExternalSystemTimeout Ein angeschlossenes System antwortet nicht innerhalb einer akzeptablen Zeit Error ExternalSystem An einem angeschlossenen System ist ein Fehler aufgetreten Error ObjectNotFound Eine angeforderte Entität wurde nicht gefunden 1.10 Basistypen Wiederkehrende Datentypen werden im folgenden beschrieben. Sie können Teil der API-Ressourcen sein GeoJson Beschreibung beschreibt einen geographischen Punkt oder Bereich verwendet wird der GeoJson-Standard (Version 1.0) Wird als Position oder Centroid Element an der Schnittstelle ausgeliefert. Mögliche Typen: Point Polygon

8 Linestring Multipolygon Collection Referenz Collection Beschreibung Allgemeines Objekt, welches eine Liste mit Objekten einer speziellen Ressource beinhaltet Struktur Die eigentlichen Ressourcen befinden sich als Array im Element items. Im Element size wird die Größe der gesamten Ergebnisliste angegeben, die Anzahl der angezeigten Elemente kann kleiner sein. Die maximale Menge an Objekten unter items wird im Element limit angeben. Dies ist gleichzeitig ein Parameter, den der Client steuern kann. Je nach Ressource kann es hier einen anderen maximalen Wert geben. Der Wert im Element offset gibt an, wieviele Elemente der Ergebnisliste übersprungen wurden. Auch dieser Parameter kann vom Client gesetzt werden in der Anfrage und ermöglicht so ein Blättern durch große Ergebnislisten. Beispiel " &begin= t15:00:00+02:00&end= t16:00:00+02:00&offset=1&li mit=10", "offset": 1, "limit": 10, "size": 10, "items": Ausnahmebehandlung ist offset über size-angabe wird eine leere Liste zurückgegeben ist limit über size-angabe wird eine Liste mit der größe size zurückgeben Attributes Attributes stellen Key/Value-Paare mit Zusatzinformationen zu einer Ressource dar. Sie sind in der Dokumentation beispielhaft dargestellt und besitzen folgende Eigenschaften: Sie müssen nicht bei jeder Ausprägung gesetzt sein. Sie können kontextspezifisch (Beispiel: providerspezifisch) sein. Sie können während der Betriebsdauer der Schnittstelle wieder abgekündigt werden (Beispiel: providerspezifisch Keys, die beim Verlassen des Providers nicht mehr bedient werden) Sie können verwendet werden, um ressourcenspezifische Informationen abzubilden (etwa Detailinformationen zu einer bestimmten Area)

9 1.11 Parameterdefintion Mögliche Parameter und Kombinationen sind in den REST-Methoden tabellarisch aufgeführt. Folgende Attribute beschreiben, wie Parameter in den Methoden verwendet werden. Typ R C O Beschreibung verpflichtender Parameter (required) Auswahl (choice) optionaler Parameter (optional) 1.12 Expands Um den Network Traffic und CPU Belastung an der Rest API einzuschränken, wird das expand-feature benutzt. Wenn eine Rest Ressource dieses Feature benutzt, werden Teile dieser Ressource nur als Referenz dargestellt. Um bestimmte ausgeblendete Subelementen anzuzeigen, können diese über den Requestparameter expand aufgeklappt werden. Request ohne Expand GET n= &radius=2000&limit=10&providernetwork=1 HTTP/ OK Content-Type: application/json; Content-Encoding: UTF-8; " on= &radius=2000&limit=10&providernetwork=1", "offset": 0, "limit": 10, "size": 3, "items": " "expand": "provider,providernetwork,area,category,rentalobject,price", "rentalobject": " 0059a85e9d" "position": "type": "Point", "coordinates": ,

10 "_links": "rel": "self", " "distance": " "expand": "provider,providernetwork,area,category,rentalobject,price", "rentalobject": " 0059a85e6b" "position": "type": "Point", "coordinates": , "_links": "rel": "self", " "distance": " "expand": "provider,providernetwork,area,category,rentalobject,price", "rentalobject":

11 " 0059a85ecf" "position": "type": "Point", "coordinates": , "_links": "rel": "self", " "distance":

12 Request mit Expand GET n= &radius=2000&limit=10&providernetwork=1&expand=rentalobject HTTP/ OK Content-Type: application/json; Content-Encoding: UTF-8; " on= &radius=2000&limit=10&providernetwork=1&expand=rentalobject", "offset": 0, "limit": 10, "size": 3, "items": " "expand": "provider,providernetwork,area,category,rentalobject,price", "rentalobject": " ects/56321e8e77490b0059a85e9d", "uid": "56321e8e77490b0059a85e9d", "name": "Renault Zoe Elektro", "provider": "name": "EMIL" "providerrentalobjectid": "153434", "type": "vehicle", "rentalmodel": "stationbased", "category": "name": "Kleinwagen" "attributes": "doors": 5, "colour": "weiss",

13 "fuel": "electric", "licenseplate": "S-549RL", "seats": 5 "position": "type": "Point", "coordinates": , "_links": "rel": "self", " "distance": " "expand": "provider,providernetwork,area,category,rentalobject,price", "rentalobject": " ects/56320e b0059a85e6b", "uid": "56320e b0059a85e6b", "name": "Mitsubishi i-miev", "provider": "name": "EMIL" "providerrentalobjectid": "150941", "type": "vehicle", "rentalmodel": "stationbased", "category": "name": "Kleinwagen" "attributes": "doors": 5, "colour": "weiß", "fuel": "electric",

14 "licenseplate": "S-373RD", "seats": 4 "position": "type": "Point", "coordinates": , "_links": "rel": "self", " "distance": " "expand": "provider,providernetwork,area,category,rentalobject,price", "rentalobject": " ects/56321e8f77490b0059a85ecf", "uid": "56321e8f77490b0059a85ecf", "name": "Nissan env200 Combi", "provider": "name": "EMIL" "providerrentalobjectid": "170442", "type": "vehicle", "rentalmodel": "stationbased", "category": "name": "Kleinwagen" "attributes": "doors": 4, "colour": "Gelb", "fuel": "electric", "licenseplate": "PT-4614O",

15 "seats": 2 "position": "type": "Point", "coordinates": , "_links": "rel": "self", " "distance":

16 2 Ressourcen Die APIv1 unterstützt aktuell JSON Ressourcen. 2.1 Index Dienst Der Index der API liefert alle Basis-Links zum weiteren Browsen der Clients. Request GET /index Hierfür muss der Client einen HTTP GET Request auf die Ressource index machen. GET Request-Beispiel Response

17 HTTP/ OK Content-Type: application/json; Content-Encoding: UTF-8; Response-Beispiel " "name": "Services Index", "description": "HAL API Services Index", "_links": "rel": "self", " "rel": "providernetworks", " "rel": "areas", " "rel": "bookingproposals", " "rel": "providers", " 2.2 Bookingproposals (Buchungsvorschläge) Buchungsvorschläge sind Mietobjekte, die unter bestimmten Kriterien zur Nutzung bereitgestellt werden. Sie sind Ergebnisse auf Anfragen wie: "z eige alle verfügbaren Fahrzeuge für Köln im Radius 500 Meter an". Die Anfragekriterien zur Erstellung von Buchungsvorschlägen werden in Form von HTTP-Queryparameter an die API übertragen. Veränderung der Gesamtergebnismenge Die Gesamtergebnismenge wird im size Element wiedergeben. Dieser Wert kann sich bei einer erneuten Anfrage aufgrund hoher Nutzungsfrequenz auch innerhalb kürzester Zeit verändern. Das Verhalten trifft insbesondere bei einen großen Suchradius zu. Damit kann es auch zu einer Verschiebung/Neusortierung der Ergebnismengen kommen, beispielsweise wenn ein Mietobjekt in unmittelbarer Nähe während der Suchanfragen zurückgegeben wird. Dieser Sachverhalt muss bei der Implementierung eines clientseitigen Pagenation-Algorithmus mit berücksichtigt werden.

18 Request GET /bookingproposals Zum Suchen nach Buchungsvorschlägen muss der Client einen HTTP GET Request auf die Resource bookingproposals machen. Request-Beispiel GET &radius=1000&begin= T15:07:00+02:00&end= T16:10:00+ 02:00&limit=50&offset=5 Parameter der Anfrage Name Datentyp Art Info R lat Double Query Latitude des Mittelpunkts des Suchkreises (WGS84). R lon Double Query Longitude des Mittelpunkts des Suchkreises (WGS84). O radius Integer Query Radius des Suchkreises in Meter. Maximum ist 10000, Minimum ist 100.Default ist 500. O begin DateTime Query Startzeit der Buchungsanfrage (im UTC-Format). O end DateTime Query Endezeit der Buchungsanfrage (im UTC-Format). O expand String Query Kommaseparierte Liste von Subobjekten, die im Detail geliefert werden sollen: rentalobject area price O offset Integer Query Wieviele Einträge des Suchergebnisses sollen übersprungen werden (für Blättern). Default ist 0. O limit Integer Query Maximale Anzahl der Suchergebnisse. Maximum ist 50. Minimum ist 1. Default ist 25. R providernetwork String Query Filter auf Provider Netzwerk-UID (Bsp: Flinkster beinhaltet ebenfalls: TeilAuto, EinfachMobil, BookAndDrive,...) Mögliche Werte: UID Beschreibung 1 Flinkster-Netzwerk 2 CAB-Netzwerk 3 Car2Go-Netzwerk Response Die Antwort wird als Collection Objekt geschickt. Responsebeispiel ngproposals?providernetwork=1&lat= &lon= &expand=area,rent alobject,price HTTP/ OK Content-Type: application/json; Content-Encoding: UTF-8; " ingproposals?providernetwork=1&lat= &lon= &expand=area,ren talobject,price",

19 "offset": 0, "limit": 25, "size": 2, "items": "expand": "area,rentalobject,price", "rentalobject": " idernetworks/1/rentalobjects/564d82bad aa9f155", "uid": "564d82bad aa9f155", "name": "Ford Fiesta", "description": "1,6 Diesel 70kW NAVI", "provider": " iders/1" "providerrentalobjectid": "167757", "type": "vehicle", "rentalmodel": "stationbased", "category": " idernetworks/1/categories/1001" "attributes": "doors": 5, "colour": "silber", "fuel": "diesel", "licenseplate": "F-R 8788", "seats": 5 "area": " s/5639e34fb9d821005aab70a5", "uid": "5639e34fb9d821005aab70a5", "name": "Hauptbahnhof A (Berlin)", "provider": " iders/1" "providerareaid": "400657", "type": "station", "geometry": "position": "type": "Point", "coordinates": ,

20 "address": "street": "Clara-Jaschke-Straße", "zip": "10557", "city": "Berlin", "district": "Mitte", "isocountrycode": "DE" "attributes": "parking": "Zugang vom Bahnhof:..", "locationnote": "Die Stellplätze befinden sich im Parkhaus des Hauptbahnhofes auf der Ebene P-3, Zugang A. Die Stellflächen sind mit einem Schild reserviert.\r\n", "publictransportation": "S-Bahn: S5, S7, S75, S9 \r\nbus: TXL, 120, 123, 147, 240, 245, M41, M85, N20, N40 \r\nregionalbahn: RE1, RE2, RE3, RE4, RE5, RE7, RB14 \r\n" "position": "type": "Point", "coordinates": , "distance": , "price": " idernetworks/1/prices?isocountrycode=de&category=1001", "items": "interval": 60, "type": "time", "preferredprice":true, "grossamount": 5, "currency": "EUR", "taxrate": 0.19 "interval": 1440, "type": "time", "preferredprice":false, "grossamount": 50, "currency": "EUR", "taxrate": 0.19 "type": "distance", "preferredprice":true, "grossamount": 0.18,

21 "currency": "EUR", "taxrate": 0.19 "expand": "area,rentalobject,price", "rentalobject": " idernetworks/1/rentalobjects/564d85f4d aa9fc1e", "uid": "564d85f4d aa9fc1e", "name": "Mercedes C-Klasse Kombi", "description": "200 Diesel 100kW NAVI ", "provider": " iders/1" "providerrentalobjectid": "156313", "type": "vehicle", "rentalmodel": "stationbased", "category": " idernetworks/1/categories/1003" "attributes": "doors": 5, "colour": "silber", "fuel": "diesel", "licenseplate": "F-R 8449", "seats": 5 "area": " s/5639e366b9d821005aab719a", "uid": "5639e366b9d821005aab719a", "name": "Hauptbahnhof C", "provider": " iders/1" "providerareaid": "402268", "type": "station", "geometry": "position": "type": "Point", "coordinates":

22 , "address": "street": "Clara-Jaschke-Straße", "zip": "10557", "city": "Berlin", "district": "Mitte", "isocountrycode": "DE" "attributes": "parking": "Zugang vom Bahnhof", "publictransportation": "S-Bahn: S5, S7, S75, S9 \r\nbus: TXL, 120, 123, 147, 240, 245, M41, M85, N20, N40 \r\n" "position": "type": "Point", "coordinates": , "distance": , "price": " idernetworks/1/prices?isocountrycode=de&category=1003", "items": "interval": 60, "type": "time", "preferredprice":true, "grossamount": 7, "currency": "EUR", "taxrate": 0.19 "interval": 1440, "type": "time", "preferredprice":false, "grossamount": 70, "currency": "EUR", "taxrate": 0.19 "type": "distance", "preferredprice":true, "grossamount": 0.2, "currency": "EUR", "taxrate": 0.19

23 , "_links": "rel": "GooglePlayStore", " "rel": "AppleAppStore", "

24 rentalinformation Zusätzliche Informationen zu besonderen Mietparametern. Beispiele: begin: Der Mietbeginn, welcher für dieses Mietobjekt zulässig ist. Bei stationärem Carsharing ist bspw. zumeist nur ein 15min. Raster gültig. Bei Freefloating- oder Fahrradangeboten ist der Buchungsbeginn hingegen minutengenau möglich. Diese Rückgabe kann zur Vorbelegung der Datumsauswahl beim Mietbeginn verwendet werden. end: Analog zu begin, nur für das Mietende. Hat end den Wert null, so handelt es sich um eine Miete mit offenem Ende (Open end). Dies ist bspw. bei Freefloating und Fahrradvermietung häufig der Fall. _links (innerhalb der Liste / außerhalb des BookingProposals): Definiert URIs die an die Liste direkt angehangen werden können: GooglePlayStore: URI - Aussprung in die Android App Store Seite der App AppleAppStore: URI - Aussprung in die IOS App Store Seite der App _links (innerhalb eines BookingProposals): Vorrausetzung ist ein expand auf rentalobject sowie die Angabe eine Endzeit Definiert URIs die an ein BookingProposal gehangen werden können: AppBookingLink: URI - Aussprung in die Mobile App zum Durchbuchen eines Buchungsvorschlags Hinweis: Der Wert "size" ist nicht konstant, da Mietobjekte genutzt werden und somit weniger/mehr Buchungsvorschläge möglich sind. Best-Practice Verzicht auf expand bei Suche für die reine Anzeige von Geomarker Für die schnelle Anzeige von Markern auf Karte empfiehlt es sich Detailinformationen zum Mietobjekt und/oder Station über die entsprechenden Resourcen-href bei Bedarf nachzuladen. Insbesondere der expand auf Area verursacht ein erhöhtes Datenvolumen aufgrund seiner geografische Beschreibung (zum Beispiel Flächenbeschreibung bei Geschäftgebieten). Wahl eines angemessenen Suchradius Ein ungenauer Suchradius insbesondere in Ballungsräumen erzeugt eine große Ergebnismenge (size). Da die Anzahl der Buchungsvorschläge nicht konstant ist, wird somit das Navigieren durch Buchungsvorschläge erschwert. Ein genauer Suchradius reduziert die Ergebnissmenge deutlich und führt zu einer konstanteren Ergebnismenge. Mögliche Antworten der Schnittstelle: HTTP Statuscode Beschreibung 200 OK 400 Bad Request Die Anfrage-Nachricht war fehlerhaft aufgebaut. Details befinden sich im Fehlerobjekt der Antwort. 2.3 ProviderNetwork Ein Providernetzwerk fasst Provider, die eine Kooperation miteinander eingehen zusammen. Für den Endkunden soll hierbei kein Unterschied gemacht werden, zu welchem Provider eine Area/ Bookingproposal gehört. Aktuell existieren 3 ProviderNetworks: Flinkster-Netzwerk, beinhaltet alle Provider die zum Flinkster Netzwerk gehören (Flinkster, Teilauto, BookAndDrive, EInfachMobil,...) CAB-Netzwerk, beinhaltet alle Provider die zum CallABike-Netzwerk gehören (CallABike, Stadtrad Hamburg, Konrad,...) Car2Go-Netzwerk, beinhaltet Car2Go Request GET providernetworks/uid Parameter der Anfrage

25 Name Datentyp Art Beschreibung R uid String Path UID des Provider Network Request-Beispiel GET Response HTTP/ OK Content-Type: application/json; Content-Encoding: UTF-8; Response-Beispiel " "uid": "1", "name": "Flinkster-Partnernetz", "desc": "Fahrzeuge von Flinkster und seiner Partner", "_links": "rel": "self", "verb": "", " Subresource: RentalObject (Mietbare Objekte) Mietobjekte können Autos, Fahrräder oder andere mietbare Gegenstände sein. Die Abfrage der Mietobjekte liefert Stammdaten sowie Detailinformation. Request GET providernetworks/uid/rentalobjects/uid Die Details zu einem Mietobjekt können als HTTP GET Anfrage mit der entsprechenden UID abgerufen werden. Parameter der Anfrage Name Datentyp Art Beschreibung R uid String Path UID des Rentalobjects O expand String Query Kommaseparierte Liste von zu erweiternden Sub-Resourcen category provider

26 Request-Beispiel GET 9d Response

27 HTTP/ OK Content-Type: application/json; Content-Encoding: UTF-8; Response-Beispiel " ects/56321e8e77490b0059a85e9d", "uid": "56321e8e77490b0059a85e9d", "name": "Renault Zoe Elektro", "expand": "category,provider", "provider": " "providerrentalobjectid": "153434", "type": "vehicle", "rentalmodel": "stationbased", "category": " tegories/1002" "attributes": "doors": 5, "colour": "weiss", "fuel": "electric", "licenseplate": "S-549RL", "seats": 5 "_links": "rel": "self", " ects/56321e8e77490b0059a85e9d" uid Eindeutige ID des Mietobjekts innerhalb der HALAPI type Der Mietobjekttyp (Auto,Pool, Fahrrad, Pedelec): vehicle: Auto vehiclepool: Autopool bike: Fahrrad pedelec: E-Bike

28 rentalmodel Vermietmodell des RentalObject: stationbased: Stationsbasiert. Fahrzeuge stehen an einem Punkt. Im Carsharing müssen die Fahrzeuge zum Mietende wieder an der Anmietstation abgestellt werden parkingarea: Parkraumquartier. Fahrzeuge stehen in einem kleinerem Gebiet. Fahrzeuge müssen zum Mietende wieder im innerhalb desselben Gebietes abgestellt werden. freefloating: Fahrzeuge stehen in einem größerem Geschäftsgebiet und können überall innerhalb desselben Gebietes zum Mietende abgestellt werden. freefloatingwithstation: Fahrzeuge können entweder in einem Geschäftsgebiet ( freefloating) oder an einer festen Station ( station) abgestellt werden. providerrentalobjectid Eindeutige ID des Mietobjekts im System des Fahrzeugbereitstellers. Diese kann bei Bedarf zum direkten Datenaustausch mit der Plattform des Bereitstellers verwendet werden. provider Anbieter des RentalObjects attributes: Name Beschreibung Type licenseplate Für Autos das KFZ-Kennzeichen, bei CallABike die Bikenummer String doors Anzahl Türen Integer model Fahrzeugmodell String seats Anzahl Sitzplätze Integer colour Farbe String maxbookingperiod Wie viele Minuten darf das Fahrzeug maximal gebucht werden? Integer minbookaheadtime reservationtime fuel Wie viel Minuten muss das Fahrzeug mindestens im Voraus gebucht werden? Verhindert kurzfristige Buchungen. Wie viel Minuten kann ein Mietfahrzeug maximal reserviert werden, bevor die Fahrt angetreten wird? (bei freefloating) Aktuell verfügbaren Werte für Kraftstoffarten (Erläuterung in Klammern hinter dem Wert sind nicht Bestandteil der Antwort in der Schnittstelle) diesel petrol (Super) electric (Strom) hybrid (Strom und Benzin) lpg_compressedgas (Erdgas, mono) multifuel (Erdgas mit Nottank Super) ethanol hydrogen (Wasserstoff) Weitere Kraftstoffarten können hinzugefügt werden. Das Fehlen des Attributs fuel bedeutet, dass die Kraftstoffart unbekannt ist. Integer Integer String Der Empfänger muss sicherstellen weitere Attributes verarbeiten zu können. _links: Definiert URIs die an ein Rentalobject angehangen werden können: self: Referenz auf sich selbst Mögliche Antworten der Schnittstelle: HTTP Statuscode Beschreibung 200 OK 404 Not Found Zur übergebenen UID wurde kein RentalObject gefunden Subresource Categories Categories sind Gruppierungen von Mietobjekten, beispielsweise Fahrzeugklassen.

29 Lesen einer Category Request GET /providernetworks/providernetworkuid/categories/uid Die Details zu einer Category können als HTTP GET-Anfrage mit der entsprechenden UID abgerufen werden. Parameter der Anfrage Name Datentyp Art Beschreibung R providernetworkuid String Path UID des ProviderNetworks R uid String Path UID der Category. Request-Beispiel GET Response HTTP/ OK Content-Type: application/json; Content-Encoding: UTF-8; Response-Beispiel " s/1002", "uid": "1002", "name": "Kompakt", "description": "Alfa Romeo", "_links": "rel": "self", " s/1002" providercategoryid Eindeutige ID der Fahrzeugklasse im System des Fahrzeugbereitstellers. Diese kann bei Bedarf zum direkten Datenaustausch mit der Plattform des Bereitstellers verwendet werden. name Der Name der Gruppierung (Fahrzeugklasse). Die Werte sind dynamisch und Änderungen sind möglich. Beispielwerte sind: Mini (ohne Navi), Multicity, Klein (teilweise ohne Navi), Kompakt, Mittel, Transporter (teilweise ohne Navi), Sonder,... price Preisstruktur siehe Resource Price Mögliche Antworten der Schnittstelle: HTTP Statuscode Beschreibung

30 200 OK 404 Not Found Zur übergebenen UID wurde keine Category gefunden Auflistung aller Categories Request GET providernetworks/uid/categories Es ist ebenfalls möglich, alle Categories aufzulisten. Hierbei muss eine HTTP GET-Anfrage ohne Parametern gestellt werden. Request-Beispiel GET Response Die Antwort wird als Collection Objekt geschickt. HTTP/ OK Content-Type: application/json; Content-Encoding: UTF-8; Response-Beispiel " s", "offset": null, "limit": null, "size": 3, "items": " s/1000", "uid": "1000", "name": "Mini (ohne Navi)", "description": "Aston Martin Cygnet", "_links": "rel": "self", " s/1000"

31 " s/1001", "uid": "1001", "name": "Klein (teilweise ohne Navi)", "description": "Alfa Romeo MiTo", "_links": "rel": "self", " s/1001" " s/1002", "uid": "1002", "name": "Kompakt", "description": "Alfa Romeo Giulietta", "_links": "rel": "self", " s/1002"

32 Mögliche Antworten der Schnittstelle: HTTP Statuscode Beschreibung 200 OK 400 Bad Request Die Anfrage-Nachricht war fehlerhaft aufgebaut. Details befinden sich im Fehlerobjekt der Antwort Subresource: Prices Request GET providernetworks/uid/prices?params Preislisten eines Providernetworks. Es handelt sich hierbei um Kunden-Endpreise. Die Queryparameter sind abhängig von der Preisfindungsstrategie des Providernetworks und hier nur beispielhaft dargestellt. Request-Beispiel GET 02 Response Die Antwort wird als Collection Objekt geschickt. HTTP/ OK Content-Type: application/json; Content-Encoding: UTF-8; Response-Beispiel " ocountrycode=de&category=1002", "offset": null, "limit": null, "size": 3, "items": "interval": 60, "type": "time", "preferredprice":true, "grossamount": 6, "currency": "EUR", "taxrate": 0.19, " ocountrycode=de&category=1002", "_links":

33 "rel": "self", " ocountrycode=de&category=1002" "rel": "tariff list", " Preise%2BGebuehren/ _Preisliste_Flinkster_web.pdf" "interval": 1440, "type": "time", "preferredprice":false, "grossamount": 60, "currency": "EUR", "taxrate": 0.19, " s/1002/prices", "_links": "rel": "self", " s/1002/prices" "rel": "tariff list", " Preise%2BGebuehren/ _Preisliste_Flinkster_web.pdf" "type": "distance", "preferredprice":true, "grossamount": 0.18, "currency": "EUR", "taxrate": 0.19, "

34 s/1002/prices", "_links": "rel": "self", " s/1002/prices" "rel": "tariff list", " Preise%2BGebuehren/ _Preisliste_Flinkster_web.pdf"

35 type: Art der Preisinformation value time distance Beschreibung Es handelt sich um einen Zeitpreis Es handelt es sich um einen Streckenpreis (pro km/...) interval: Zeitabschnitt in Minuten (bei type==time) grossamount: bei type==time:bruttopreis pro interval, bei type==distance: Preis pro Kilometer currency: Währung in der ein Preis angegeben ist preferredprice: Kann die Preisinformation als Standardwert für die Beauskunftung verwendet werden (preferredprice == true). Je Klasse und Type gibt es dabei nur Preiseintrag, der preferredprice == true beinhaltet. taxrate: Steuersatz Mögliche Antworten der Schnittstelle: HTTP Statuscode Beschreibung 200 OK 400 Bad Request Die Anfrage-Nachricht war fehlerhaft aufgebaut. Details befinden sich im Fehlerobjekt der Antwort. 404 Not Found Es existiert keine Preisliste für die Category 2.4 Area (Gebiete) Gebiete sind geographische Bereiche, die für den Mietvorgang oder die Beauskunftung relevant sind Lesen eines Areals Request GET /areas/uid Die Details zu einem Areals können als HTTP GET-Anfrage mit der entsprechenden UID abgerufen werden. Parameter der Anfrage Name Datentyp Art Beschreibung R uid String Path UID des Areals. O expand String Query Kommaseparierte Liste von Subobjekten, die im Detail geliefert werden sollen: provider Request-Beispiel GET Response

36 HTTP/ OK Content-Type: application/json; Content-Encoding: UTF-8; Response-Beispiel " "uid": "55ffec2b1e423b26ea146b8c", "name": "Sanderring", "providerareaid": "405637", "expand": "provider", "provider": " "type": "station", "geometry": "position" : "type": "Point", "coordinates": , "address": "street": "Virchowstraße", "number": "1", "zip": "97072", "city": "Würzburg", "district": "Sanderau", "isocountrycode": "DE" "attributes": "key": "value" "_links": "rel": "self", " name: Name des Gebiets type: Typangabe für das Gebiet, folgende Werte sind möglich: Wert Beschreibung

37 station parkingarea operationarea gasstation unknown feste Standort für eine Car- oder Bikesharingstation Parkraumquartier: Fläche innerhalb dessen die Fahrzeuge abgestellt werden Geschäftsgebiet: größeres Gebiet innerhalb dessen die Fahrzeuge entliehen und verwendet werden Tankstelle unbekannte Angabe attributes: area/type Name Beschreibung Type station,parkingarea locationnote Beschreibung der Lage der Station String station,parkingarea publictransportation Beschreibung der ÖPNV-Anbindung String station,parkingarea access Hinweise zur Bedienung des Zugangs String station,parkingarea parking Beschreibung der Stellplätze String Der Empfänger muss sicherstellen weitere Attributes verarbeiten zu können. geometry Kann bis zu 2 Unterelemente beinhalten: position: Die Position der Area als GeoJson centroid: Für den Fall das es sich bei der Position nicht um einen Punkt handelt (type: Point), wird in Centroid der Mittelpunkt der Fläche bereit gestellt. Mögliche Antworten der Schnittstelle: HTTP Statuscode Beschreibung 200 OK 404 Not Found Zur übergebenen UID wurde kein Areal gefunden Suche nach Arealen Request GET /areas? Es ist ebenfalls möglich, nach Arealen zu suchen. Hierbei muss eine HTTP GET-Anfrage mit der entsprechenden Parametern gestellt werden. Request-Beispiel GET s=1000&limit=5 Parameter der Anfrage Name Art Art Info R lat Double Query Latitude des Mittelpunkts des Suchkreises (WGS84) R lon Double Longitude des Mittelpunkts des Suchkreises (WGS84) Query O radius Integer O type String O provider Integer Query Query Query Radius des Suchkreises in Meter. Maximum ist 10000, Minimum ist 100. Default ist 500. Filter auf Stationen eines bestimmten Typs (bspw. station) Filter auf Stationen eines bestimmten Providers (bspw. CallABike)

38 O offset Integer O limit Integer O expand String Query Query Query Wieviele Einträge des Suchergebnisses sollen übersprungen werden (für Blättern). Default ist 0. Maximale Anzahl der Suchergebnisse. Maximum ist 50. Default ist 25. Kommaseparierte Liste von Subobjekten, die im Detail geliefert werden sollen: provider R providernetwork String Query Filter auf Provider Netzwerk-UID (Bsp: Flinkster beinhaltet ebenfalls: TeilAuto, EinfachMobil, BookAndDrive,...) Mögliche Werte: UID Beschreibung 1 Flinkster-Netzwerk 2 CAB-Netzwerk 3 Car2Go-Netzwerk Response Die Antwort wird als Collection Objekt geschickt. HTTP/ OK Content-Type: application/json; Content-Encoding: UTF-8; Response-Beispiel " it=25&providernetwork=1", "offset":0, "limit":25, "size":2, "items": " "uid":"55ffec2b1e423b26ea146b8c", "name":"sanderring", "providerareaid":"405637", "type":"station", "geometry": "position": "type":"point", "coordinates": ,

39 "address": "street":"virchowstraße", "number":"1", "zip":"97072", "city":"würzburg", "district":"sanderau", "isocountrycode":"de" "provider": " "_links": "rel":"self", "verb":"get", " " "uid":"55ffec101e423b26ea146601", "name":"hauptbahnhof", "providerareaid":"138", "provider": " "type":"operationarea", "geometry": "position": "type":"polygon", "coordinates": , , , , , , , , ,

40 "centroid": "type":"point", "coordinates": , "address": "street":"zum Bahnhof", "number":"15", "zip":"19053", "city":"schwerin", "district":"schwerin", "isocountrycode":"de" "provider": " "_links": "rel":"self", "verb":"get", "

41 Mögliche Antworten der Schnittstelle: HTTP Statuscode Beschreibung 200 OK 400 Bad Request Die Anfrage-Nachricht war fehlerhaft aufgebaut. Details befinden sich im Fehlerobjekt der Antwort. 2.5 Provider Provider stellen Mobilitätsdienstleistungen zur Verfügung Lesen eines Providers Request GET /providers/uid Parameter der Anfrage Name Datentyp Art Beschreibung R uid Integer Path UID des Providers GET Request-Beispiel Response HTTP/ OK Content-Type: application/json; Content-Encoding: UTF-8; Response-Beispiel " "uid": "1", "name": "Flinkster (Endkd.)", "description": "Deutsche Bahn Connect GmbH", "_links": "rel": "self", " Mögliche Antworten der Schnittstelle: HTTP Statuscode Beschreibung

42 200 OK 404 Not Found Zur übergebenen UID wurde keine Provider gefunden.