1.3.1 Metaportal

Aktuell verlieren sich Fahrt-Anbieter und Mitfahrer von Mitfahrgelegenheiten auf den über 50 Mitfahrportalen, Apps u.v.m.. Darüber hinaus gibt es noch zahlreiche interne und / oder analoge Systeme wie Mitfahrbänke.

Es bräuchte also eine spezielle Suchmaschine, welche Zugriff auf alle Daten aller Mitfahrbörsen hat und so Nutzer schnell über alle Plattformen hinweg Fahrten suchen können. Diese Suchmaschine wäre das schon mehrfach zuvor angesprochene Meta-Portal.

Ein Meta-Portal würde von möglichst vielen Mitfahr-Plattformen Daten aggregieren und zusammenfügen. Es hätte lediglich Fahrt-Informationen und wäre so eine rein anonyme Suchmaschine: Die Kontaktaufnahme würde weiterhin auf der Plattform geschehen, in welcher der Fahrer die Fahrt eingestellt hat.

Darüber hinaus könnte das Metaportal die aggregierten Daten normalisieren, automatisiert veredeln und wiederum via ridesharing.api zur Verfügung stellen. Dies würde den Aufwand einer Vernetzung zwischen den Portalen reduzieren, da Fehler einmal auf der Metaplattform statt bei jedem Datenimport einer Mitfahrbörse ausgebügelt werden können. Außerdem könnte das Meta-Portal dieselben Daten auch über moderne Schnittstellen wie z.B. Websockets bereitstellen, selbst wenn das ursprüngliche Portal dies nicht kann.

1.3.2 Multimodalität

Ridesharing funktioniert dann ganz besonders gut, wenn man es mit dem öffentlichen Nahverkehr verbindet. Denn gerade, wenn MitfahrerInnen zwischendurch dazusteigen wollen, hängt vom Wahl des Treffpunktes die Effizienz der gesamten Fahrt ab. Bei Langstrecken-Fahrten lohnt es sich oft, einen Treffpunkt außerhalb der Innenstadt zu wählen. Und auch bei Pendelfahrten lohnt es sich, den Mitfahrenden nicht unbedingt von zu Hause aus abzuholen.

Moderne Routing-Engines bringen alles mit, um Mitfahrgelegenheiten und ÖPNV optimal zu verknüpfen. Um jedoch zu funktionieren, brauchen Routing-Engines standardisierte Rohdaten. Viele Routing-Engines funktionieren mit GTFS sowie GTFS-RT, so dass ein Datenstandard für Mitfahrgelegenheiten bestmöglich in GTFS umformbar sein sollte.

1.3.3 Export von Profildaten

Da es zahlreiche Ridesharing-Plattformen gibt, sollte es eine Möglichkeit geben, dass Nutzer ihre persönlichen Einstellngen und Präferenzen auf einer Plattform exportieren und auf einer anderen importieren können. Mit der DSGVO ist dieses eh wünschenswerte Feature verpflichtend geworden.

Vielfach scheitert dieses Anliegen aber noch an dem Datenformat, da man aktuell eher CSVs und Textdateien statt strukturierte Daten bekommt. Dies kann die ridesharing.api ändern, indem es ein JSON-Datenmodell definiert und so die Plattformen in weiten Teilen untereinander kompatibel macht.

Praktisch sähe das dann so aus, dass ein Nutzer beim Export seiner Nutzerdaten eine einzige JSON-Datei herunterladen könnte. Wenn die Ziel- Plattform das unterstützt, könnte der Nutzer die Datei dann auf der Ziel- Plattform hochladen und hätte so ganz einfach sämtliche Einstellungen übertragen.

1.5.1 Zwingende, empfohlene und optionale Anforderungen

Diese Spezifikation nutzt müssen, können und sollten in einer eindeutig definierten Art und Weise. Diese ist angelehnt an die Definitionen der Begriffe MUST, SHOULD und MAY (bzw. MUST NOT, SHOULD NOT und MAY NOT) aus RFC2119.¹

Die Bedeutung im Einzelnen:

müssen/muss bzw. zwingend:

Die Erfüllung einer so gekennzeichneten Anforderung ist zwingend erforderlich.

Die Entsprechung in RFC2119 lautet "MUST", "REQUIRED" oder "SHALL".

nicht dürfen/darf nicht:

Dieses Stichwort kennzeichnet ein absolutes Verbot.

Die Entsprechung in RFC2119 lautet "MUST NOT" oder "SHALL NOT".

sollten/sollte bzw. empfohlen:

Mit dem Wort sollten bzw. sollte sind empfohlene Anforderungen gekennzeichnet, die von jeder Implementierung erfüllt werden sollten. Eine Nichterfüllung ist als Nachteil zu verstehen, beispielsweise weil die Nutzerfreundlichkeit dadurch Einbußen erleidet, und sollte daher sorgfältig abgewogen werden.

Die Entsprechung in RFC2119 lautet "SHOULD" oder "RECOMMENDED".

sollten nicht/sollte nicht bzw. nicht empfohlen:

Diese Formulierung wird verwendet, wenn unter gewissen Umständen Gründe existieren können, die ein bestimmtes Verhalten akzeptabel oder sogar nützlich erscheinen lassen, jedoch die Auswirkung des Verhaltens vor einer entsprechenden Implementierung verstanden und abgewogen werden sollten.

Die Entsprechung in RFC2119 lautet "SHOULD NOT" oder "NOT RECOMMENDED".

dürfen/darf bzw. optional:

Mit dem Wort dürfen bzw. darf oder optional sind optionale Bestandteile gekennzeichnet. Ein Anbieter könnte sich entscheiden, den entsprechenden Bestandteil aufgrund besonderer Kundenanforderungen zu unterstützen, während andere diesen Bestandteil ignorieren könnten. Implementierer von Clients oder Servern dürfen in solchen Fällen nicht davon ausgehen, dass der jeweilige Kommunikationspartner den entsprechenden, optionalen Anteil unterstützt.

Die Entsprechung in RFC2119 lautet "MAY".

1.5.2 Geschlechterspezifische Begrifflichkeiten

Um bei Begriffen wie Nutzer, Anwender, Betreiber etc. die sonst übliche Dominanz der männlichen Variante zu vermeiden, werden in diesem Dokument männliche und weibliche Varianten gemischt. Gemeint sind in allen Fällen Personen jeglichen Geschlechts.

1.5.3 Codebeispiele

Die in diesem Dokument aufgeführten Codebeispiele dienen der Veranschaulichung der beschriebenen Prinzipien. Es handelt sich um frei erfundene Daten.

Codebeispiele erheben insbesondere bei JSON-Code nicht den Anspruch auf syntaktische Korrektheit und Vollständigkeit. Dementsprechend können in Codebeispielen Auslassungen vorkommen, die mit ... gekennzeichnet werden.

1.5.4 Namespace-Präfixe für Objekt- und Datentypen

Bei der Erwähnung von Objekttypen, die in dieser Spezifikation beschrieben werden, wird in der Regel ein Präfix ridesharing-api: vor den Namen gesetzt, z. B. "ridesharing-api:Trip". Damit soll verdeutlicht werden, dass der Objekttyp innerhalb der ridesharing.api-Spezifikation gemeint ist.

Das Präfix ridesharing-api: steht hierbei für die folgende Namespace-URL:

https://schema.ridesharing-api.org/1.1/

Dadurch kann eine Typenangabe wie ridesharing-api:Trip eindeutig in die folgende URL übersetzt werden:

https://schema.ridesharing-api.org/1.1/Trip

2.1.1 Aufbauen auf gängiger Praxis

Grundlage für die Erarbeitung der ridesharing.api-Spezifikation in der vorliegenden Version ist eine Analyse von aktuell (2018 - 2019) in Deutschland etablierten Ridesharing-Angeboten. Erklärtes Ziel für diese erste Version ist es, mit möglichst geringem Entwicklungsaufwand auf Seite der Plattformanbieter. Für die ridesharing.api-Spezifikation wurde sozusagen ein Datenmodell als "gemeinsamer Nenner" auf Basis der gängigen Praxis konstruiert.

2.1.2 Verbesserung gegenüber dem Status Quo wo möglich

Dort, wo es dem Ziel der einfachen Implementierbarkeit und der einfachen Migration nicht im Weg steht, erlauben sich die Autoren dieser Spezifikation, auch Funktionen aufzunehmen, die noch nicht als gängige Praxis im Bereich der Ridesharing-Plattformen bezeichnet werden können oder welche nur von einzelnen Systemen unterstützt werden. Solche Funktionen sind dann so integriert, dass sie nicht als zwingende Anforderung gelten.

Als Beispiel wäre die Fähigkeit zu Websocket-basierten Live-Updates zu nennen. Diese sind nicht verpflichtend, sind aber eine sinnvolle Erweiterung, die mit demselben Datenmodell realisierbar sind.

2.1.3 Selbstbeschreibungsfähigkeit

Ausgaben des Servers sollten so beschaffen sein, dass sie für menschliche Nutzerinnen weitgehend selbsterklärend sein können. Dies betrifft besonders die Benennung von Objekten und Objekteigenschaften.

Um den Kreis der Entwicklerinnen und Entwickler, die mit einer ridesharing.api arbeiten können, nicht unnötig einzuschränken, wird hierbei grundsätzlich und soweit sinnvoll auf englischsprachige Begrifflichkeiten gesetzt.

2.1.4 Erweiterbarkeit

Implementierer sollen in der Lage sein, über eine ridesharing.api-konforme Schnittstelle auch solche Informationen auszugeben, die nicht im Rahmen des ridesharing.api-Schemas abgebildet werden können. Dies bedeutet zum einen, dass ein System Objekttypen unterstützen und ausliefern darf, die nicht (oder noch nicht) im ridesharing.api-Schema beschrieben sind. Das bedeutet auch, dass Objekttypen so um eigene Eigenschaften erweitert werden können, die nicht im ridesharing.api Schema beschrieben sind.

Ein weiterer Aspekt betrifft die Abwärtskompatibilität, also die Kompatibilität von ridesharing.api-Clients mit zukünftigen Schnittstellen. So können beispielsweise zukünftige Erweiterungen des ridesharing.api-Schemas, etwa um neue Objekttypen, genauso durchgeführt werden, wie die Erweiterungen um herstellerspezifische Objekttypen. Ein Client muss diese Anteile nicht auswerten, sofern sie nicht für die Aufgabe des Clients relevant sind. Es bedeutet im Umkehrschluss allerdings auch, dass ein Client nicht fehlschlagen darf, falls derartige Erweiterungen vorhanden sind.

2.1.5 Browseability/Verlinkung

Klassische Webservice-Schnittstellen erfordern von den Entwicklern vollständige Kenntnis der angebotenen Einstiegspunkte und Zugriffsmethoden, gepaart mit sämtlichen unterstützten URL-Parametern, um den vollen Funktionsumfang der Schnittstelle ausschöpfen zu können.

Ridesharing-Angebote sind weitgehend in Form von Graphen aufgebaut. Das bedeutet, dass Objekte häufig mit einer Vielzahl anderer Objekte verknüpft sind. So hat eine Fahrt mehrere Stops, an denen Personen in Form einer Participation ein- oder aussteigen. Gleichzeitig können Personen Autos besitzen, die wiederum bei mehreren angebotenen Fahrten eingesetzt werden.

Eine ridesharing.api-Schnittstelle gibt jedem einzelnen Objekt eine eindeutige Adresse, eine URL. Somit kann die Schnittstelle den Verweis von einem Objekt, beispielsweise einem Gremium, auf ein anderes Objekt, etwa ein Mitglied des Gremiums, dadurch ausgeben, dass im Kontext des Gremiums die URL des Mitglieds ausgeben wird. Der Client kann somit ausgehend von einem bestimmten Objekt die zugehörigen Objekte im System finden, indem er einfach den angebotenen URLs folgt. Dieses Prinzip wird auch "Follow Your Nose"² genannt.

2.3.1 URL-Kanonisierung

Um Objekte eindeutig identifizieren zu können ist es notwendig, dass ein Server für ein Objekt genau eine unveränderliche URL benutzt. Diese Festlegung auf genaue eine eindeutige URL wird Kanonisierung genannt. Ein Server muss deshalb für jedes seiner Objekte eine kanonische URL bestimmen können.

Es wird empfohlen keine IP-Adressen in URLs zu benutzen, sondern einen mit Bedacht gewählten Hostnamen einzusetzen. Das ist vor allem im Hinblick auf die Langlebigkeit der URLs wichtig.

Um die Kanonisierung zu gewährleisten sollten ridesharing.api-Server so konfiguriert werden, dass sie nur über eine bestimmte Domain erreichbar sind. ridesharing.api-Server sollten dagegen möglichst nicht nur über eine IP-Addresse sowie möglichst auch nicht über weitere, nicht kanonische URLs erreichbar sein.

Wenn ein Server auch durch eine nicht-kanonische URL erreichbar ist, dann sollte eine entsprechende HTTP-Anfrage mit einer Weiterleitung auf die entsprechende kanonische URL und HTTP-Status-Code 301 beantwortet werden. Zur Überprüfung kann z.B. der Host-Header einer HTTP-Anfrage verwendet werden.

Beim Pfad-Bestandteil der URL müssen Server-Implementierer darüber hinaus beachten, dass zur kanonischen Schreibweise auch die Groß- und Kleinschreibung, die Anzahl von Schrägstrichen als Pfad-Trennzeichen und die Anzahl von führenden Nullen vor numerischen URL-Bestandteilen gehört.

Die Kanonisierung umfasst auch den Query-String-Bestandteil der URL. Wie auch beim Pfad gilt, dass für jeden Parameter und jeden Wert im Query-String genau eine kanonische Schreibweise gelten muss.

Darüber hinaus sollte der Server-Implementierer darauf achten, Query-String-Parameter immer nach demselben Prinzip zu sortieren. Als Beispiel: Die beiden URLs

https://ridesharing.example.org/stops?person=1&trip=2
https://ridesharing.example.org/stops?trip=2&person=1

unterscheiden sich lediglich in der Reihenfolge der Query-String-Parameter. Da sie jedoch nicht identisch sind, könnten Clients annehmen, dass beide URLs verschiedene Objekte repräsentieren.

Clients sollen die vom Server gelieferten URLs bei Anzeige, Speicherung und Weiterverarbeitung nicht verändern.

2.3.2 HTTP und HTTPS

Der Einsatz des verschlüsselten HTTPS wird empfohlen. Bei Verwendung von HTTPS wird allen URLs "https://" voran gestellt, ansonsten beginnen URLs mit "http://".

Aus Gründen der URL-Kanonisierung ist es zwingend notwendig, dass ein Server-Betreiber sich entweder für HTTP oder für HTTPS entscheidet. Es jedoch möglich, eine Weiterleitung (HTTP Status-Code 301) einzurichten. Eine Weiterleitung von HTTPS auf HTTP wird nicht empfohlen.

2.3.3 Langlebigkeit

Weiterhin sollen URLs langlebig sein, sodass sie möglichst lange zur Abfrage des dazugehörigen Objekts verwendet werden können.

In URLs sollten deshalb nur Eigenschaften des Objekts aufgenommen werden, die nicht verändert werden. Ändert sich beispielsweise die Kennung einer Drucksache im Verlauf ihrer Existenz, dann scheidet sie für die Bildung der URL aus.

Des Weiteren sollen Eigenschaften der Implementierung nicht sichtbar sein. Ist ein ridesharing.api-Server beispielsweise in PHP geschrieben, sollte dies nicht dazu führen, dass im Pfad ein Bestandteil wie "ridesharing.php/" erscheint.

Weitere Empfehlungen für langlebige URLs liefern Tim Berners-Lee⁴ sowie die Europäische Kommission⁵.

2.4.1 In der ridesharing.api verwendete Datentypen

In ridesharing.api werden alle in JSON definierten Dateitypen verwendet:

object:

Objects entsprechen der Definition des Objects in RFC 7159 Section 4

array:

Arrays entsprechen der Definition des Arrays in RFC 7159 Section 5

integer:

Integers entsprechen der Definition des Integer-Parts der Number aus RFC 7159 Section 6

boolean:

Booleans entsprechen der Definition von Boolean in RFC 7159 Section 3

string:

Strings entsprechen der Definition der Unicode-Strings aus RFC 7159 Section 7

In der ridesharing.api werden verschiedene String-Typen verwendet. Wenn von diesen Typen gesprochen wird, so wird automatisch ein JSON-String vorausgesetzt:

url:

Eine URL ist ein String, der entsprechend des URL-Kapitels formatiert wurde.

url (Object):

Eine URL mit in Klammern angehängtem Objektname beschreibt eine URL auf eben diesen Objekttypus.

date:

Entspricht einem Datum ohne Uhrzeit und ohne Zeitzone, wie sie im folgenden Abschnitt beschrieben werden.

date-time:

Entspricht einem Datum und einer Uhrzeit mit Zeitzone, wie sie im folgenden Abschnitt beschrieben werden.

2.4.2 Datums- und Zeitangaben

Für Datums- und Zeitangaben wird eine Spezialisierung der in ISO 8601 beschriebenen Formate verwendet. Ein Datum (date) muss muss die Form yyyy-mm-dd besitzen und ein Zeitpunkt (date-time) muss in der Form yyyy-mm-ddThh:mm:ss±hh:mm angegeben werden.

Beispiel für ein Datum: 1969-07-21

Beispiel für einen Zeitpunkt: 1969-07-21T02:56:00+00:00

2.4.3 null-Werte und leere Listen

JSON erlaubt es grundsätzlich, Eigenschaften mit dem Wert null zu versehen. Eigenschaften sollten nicht mit dem Wert null ausgegeben werden, wenn zu einer Eigenschaft keine Daten vorliegen. Obligatorische Eigenschaften dürfen nicht den Wert null haben.

Im Fall von Arrays erlaubt JSON grundsätzlich die Ausgabe von [] für leere Arrays. Wie bei null wird auch hier empfohlen, auf die Ausgabe einer Eigenschaft mit dem Wert [] zu verzichten, wenn zu einer Eigenschaft keine Daten vorliegen. Bei obligatorischen Eigenschaften muss jedoch eine leere Liste ausgegeben werden.

Bei nicht obligatorischen Eigenschaften sollte gleichermaßen auf die Ausgabe eines leeren Strings "" verzichtet werden.

2.5.1 Referenzierung von Objekten via URL

Bei der Referenzierung einzelner Objekte wird eine URL angegeben, welche auf das entsprechende Objekt verweist. Der Typ ist hierbei ein string (url: Objekt-ID). Ein Beispiel hierfür ist location in Stop:

{
    "id": "https://ridesharing-api.example-ridesharing.de/stop/1"
    "type": "https://schema.ridesharing-api.org/1.0/Stop",
    "location": "https://ridesharing-api.example-ridesharing.de/location/1",
    [...]
}

Es kann auch eine Liste von Referenzen ausgegeben werden. Der Typ ist in diesem Fall array of string (url: Objekt-ID).

Ein Beispiel hierfür ist stop in Trip:

{
    "id": "https://ridesharing-api.example-ridesharing.de/trip/1"
    "type": "https://schema.ridesharing-api.org/1.0/Trip",
    "stop": [
        "https://ridesharing-api.example-ridesharing.de/stop/1",
        "https://ridesharing-api.example-ridesharing.de/stop/2",
        [...],
    ],
    [...]
}

2.5.2 Interne Ausgabe von Objekten

Objekte können auch intern ausgegeben werden. Dabei wird das gesamte Objekt als Wert eines Attributs angegeben. Ein Beispiel für ein internes Objekt ist location in ridesharing-api:Stop:

{
    "id": "https://ridesharing-api.example-ridesharing.de/stop/1"
    "type": "https://schema.ridesharing-api.org/1.0/Stop",
    "location": {
        "id": "https://ridesharing-api.example-ridesharing.de/location/1"
        "type": "https://schema.ridesharing-api.org/1.0/Location",
        [...]
    },
    [...]
}

Ebenso kann eine Liste von Objekten intern ausgegeben werden. Hier das Beispiel des Attributes stop in ridesharing-api:Trip.

{
    "id": "https://ridesharing-api.example-ridesharing.de/trip/1"
    "type": "https://schema.ridesharing-api.org/1.0/Trip",
    "stop": [
        {
            "id": "https://ridesharing-api.example-ridesharing.de/stop/1"
            "type": "https://schema.ridesharing-api.org/1.0/Stop",
        },
        {
            "id": "https://ridesharing-api.example-ridesharing.de/stop/2"
            "type": "https://schema.ridesharing-api.org/1.0/Stop",
        },
        [...]
    ]
}

Bei der internen Ausgabe von Objekten darf der Server keine gelöschten Objekte ausgeben.

2.5.3 Externe Objektlisten

Es können auch Referenzen zu sogenannten externen Objektlisten angegeben werden. Die externe Liste enthält dann die betreffenden Objekte in Form einer Listenausgabe. Ein Beispiel dafür ist route in ridesharing-api:System.

ridesharing-api:System:

{
    "id": "https://ridesharing-api.example-ridesharing.de/system"
    "type": "https://schema.ridesharing-api.org/1.0/System",
    "route": "https://ridesharing-api.example-ridesharing.de/routes"
}

Die externe Objektliste:

{
    "data": [
        {
            "id":"https://ridesharing-api.example-ridesharing.de/route/1",
            "type": "https://schema.ridesharing-api.org/1.0/System",
            [...]
        },
        {
            "id":"https://ridesharing-api.example-ridesharing.de/route/2",
            "type": "https://schema.ridesharing-api.org/1.0/System",
            [...]
        },
        [...]
    ],
    ...
}

2.5.4 Paginierung

Für externe Objektlisten ist eine Aufteilung sogenannte Listenseiten vorgesehen, wobei jede Listenseite eine eigene URL erhält. Das dient dazu, die bei der jeweiligen Anfrage übertragenen Datenmengen und Antwortzeiten zu begrenzen.

Die Entscheidung, ob eine externe Objektliste mit Paginierung ausgegeben wird, liegt allein beim Server. Bei Listen mit mehr als 100 Einträgen wird dies empfohlen.

Ein Server muss für eine stabile Sortierung von Listeneinträgen sorgen. Das heißt, dass die Sortierung der Einträge einem konstanten Prinzip folgt und sich nicht von Abfrage zu Abfrage ändert. Das kann z.B. durch die Sortierung von Objekten nach einer eindeutigen und unveränderlichen ID erreicht werden.

Jede Listenseite muss die Attribute folgenden Attribute enthalten:

• data (Array der intern ausgegebenen Objekte)

• pagination (Object)

• links (Object)

Für pagination sind die folgenden Attribute festgelegt, die alle optional sind:

• totalElements: Gibt die Gesamtanzahl der Objekte in der Liste an. Diese Zahl kann sich unter Umständen bis zum Aufruf der nächsten Listenseiten ändern.

• elementsPerPage: Gibt die Anzahl der Objekte pro Listenseite an. Dieser Wert muss auf allen Listenseiten bis auf die letzte gleich sein.

• currentPage: Gibt die aktuelle Seitenzahl in der Liste an.

• totalPages: Gibt die Gesamtanzahl der Seiten in der Liste an.

Für links sind folgende Attribute festgelegt, die bis auf next alle optional sind:

• first: URL der ersten Listenseite

• prev: URL der vorherigen Listenseite

• self: Die kanonische URL dieser Listenseite

• next: URL der nächsten Listen. Für alle Seiten bis auf die letzte ist die Angabe dieser URL zwingend.

• last: URL der letzten Listenseite

{
    "data": [
        {...},
        {...},
        ...
    ],
    "pagination": {
        "totalElements": 50000,
        "elementsPerPage": 100,
        "currentPage": 3,
        "totalPages":500
    },
    "links": {
        "first": "https://ridesharing.example.org/trips/",
        "prev": "https://ridesharing.example.org/trips/?page=2",
        "self": "https://ridesharing.example.org/trips/?page=3",
        "next": "https://ridesharing.example.org/trips/?page=4",
        "last": "https://ridesharing.example.org/trips/?page=500",
    }
}

2.5.5 Filter

Externe Objektlisten können mit den URL-Parametern created_since, created_until, modified_since und modified_until eingeschränkt werden. Diese Parameter beziehen sich auf die entsprechenden Attribute der jeweiligen Objekte, wobei reservierte Zeichen URL-Kodiert werden müssen. Ein Server muss diese Parameter bei allen externen Objektlisten unterstützen.

Die Filter werden vom Client benutzt, indem die gewünschten URL-Parameter an die URL der ersten Listenseite angehängt werden. Bei allen weiteren Seiten, genauer gesagt bei den Werten von links, muss der Server sicherzustellen, dass die verwendeten Filter erhalten bleiben.

Ein Server muss für den im nächsten Abschnitt beschrieben Aktualisierungsmechanismus auch die den Filtern entsprechenden gelöschten Objekte ausgeben, wenn der Parameter modified_since gesetzt ist. Wenn modified_since nicht gesetzt ist, dann dürfen die gelöschten Objekte nicht ausgegeben werden. Dadurch kann sich ein Client effizient darüber informieren, welche der Objekte in seinem lokalen Bestand gelöscht wurden.

Lautet die URL für eine Liste von Drucksachen wie folgt:

https://ridesharing.example.org/trips/

kann der Client die folgende URL bilden, um die Ausgabe der Liste auf Drucksachen einzuschränken, die seit dem 1. Januar 2014 veröffentlicht wurden:

https://ridesharing.example.org/trips/?created_since=2014-01-01T00%3A00%3A00%2B01%3A00

Mehrere Parameter können auch gemeinsam verwendet werden. So kann man z.B. eine Einschränkung vom 1.1.2014 bis zum 31.1.2014 vornehmen:

https://ridesharing.example.org/trips/?created_since=2014-01-01T00%3A00%3A00%2B01%3A00&created_until=2014-01-31T23%3A59%3A59%2B01%3A00

Die genannten URL-Parameter erwarten grundsätzlich eine vollständige date-time-Angabe.

Des Weiteren kann ein Client die Anzahl der Objekte pro Listenseite durch den URL-Parameter limit begrenzen, der sich auf das gleichnamige Attribut bezieht. Ein Client darf nicht erwarten, dass sich ein Server an seine limit-Anfrage hält.

2.5.6 Der Aktualisierungsmechanismus

Der Hauptnutzen der Filter ist die Möglichkeit, einen lokalen Datenbestand inkrementell zu aktualisieren.

Ein Client könnte z.B. am 1.1.2014 um 2:00 Uhr deutscher Zeit die Liste aller Drucksachen herunterladen und in einer Datenbank speichern.

https://ridesharing.example.org/trips/

Um den Datenbestand am nächsten Tag zu aktualisieren, ruft der Client dieselbe URL auf, diesmal jedoch mit dem Parameter modified_since mit dem Wert 2014-01-01T02:00:00+01:00.

https://ridesharing.example.org/trips/?modified_since=2014-01-01T02%3A00%3A00%2B01%3A00

Diese Liste ist in der Regel deutlich kürzer als die Liste aller Objekte, sodass die Aktualisierung bedeutend schneller ist als der erste Abruf. Der Client muss außerdem nur noch eine deutlich kleinere Menge an Objekten in die Datenbank einfügen, aktualisieren oder löschen, um den gleichen Datenstand wie der Server zu haben.

3.2.1 Vollständigkeit

Alle regulär öffentlich abrufbaren Informationen sollten auch in der ridesharing.api ausgegeben werden, solange dies nicht den Datenschutzbestimmungen widerspricht. Daher sind sämtliche Felder im Schema als empfohlen zu behandeln, wenn nicht explizit etwas anderes angegeben wurde.

3.2.2 Herstellerspezifische Erweiterungen

In der ridesharing.api können zusätzliche, herstellerspezifische Eigenschaften hinzugefügt werden. Dazu wird diesen Eigenschaften ein Herstellerprefix vorangestellt. So könnte man z.B. ridesharing-api:Location um einen Point of Interest erweitern:

"BeispielHersteller:pointOfInterest": "Altes Stadttor",

3.2.3 URL-Pfade in den Beispielen

ridesharing.api-Clients wissen nichts vom Aufbau von Pfaden innerhalb von URLs, müssen dies nicht wissen, und es gibt deshalb in der ridesharing.api-Spezifikation keine Festlegungen dazu. Die in den Beispielen verwendeten URLs zeigen einen möglichen Weg zur Umsetzungen der Empfehlungen in URLs.

3.3.1 id

Die Eigenschaft id enthält den eindeutigen Bezeichner des Objekts, nämlich seine URL. Dies ist ein zwingendes Merkmal für jedes Objekt.

3.3.2 type

Objekttypenangabe des Objekts, zwingend für jedes Objekt. Der Wert ist eine Namespace-URL. Für die ridesharing.api-Objekttypen sind die folgenden URLs definiert:

3.3.3 created

Datum und Uhrzeit der Erstellung des jeweiligen Objekts.

Diese Eigenschaft muss in allen Objekttypen angegeben werden.

3.3.4 modified

Diese Eigenschaft kennzeichnet stets Datum und Uhrzeit der letzten Änderung des jeweiligen Objekts.

Diese Eigenschaft muss - genau wie created - in allen Objekttypen angegeben werden.

Es ist zwingend, dass bei jeder Änderung eines Objekts der Wert dieses Attributs auf die zu diesem Zeitpunkt aktuelle Uhrzeit gesetzt wird, da ein Client in der Regel seinen Datenbestand nur auf Basis dieses Attributs verlustfrei aktualisieren kann.

3.3.5 deleted

Falls das Objekt gelöscht wurde, muss dieses gemäß Kapitel 2.8 das Attribut deleted: true bekommen.