Unterschiede

Hier werden die Unterschiede zwischen zwei Versionen angezeigt.

--- dokumentation_der_restful_api_version_1 [2015-10-22 00:43]
Christian erstellt
+++ dokumentation_der_restful_api_version_1 [2018-11-07 18:04] (aktuell)
admin Titel gefixt
@@ Zeile 1: / Zeile 1: @@
+====== Dokumentation der RESTful API Version 1 ======
-====== Authentifizierung und Sicherheit ======
+Eine allgemeine Beschreibung der RESTful API finden Sie unter [[apis]].
+===== Authentifizierung und Sicherheit =====
 Die Authentifizierung erfolgt per Basic-HTTP-Auth mit Nutzername und
@@ Zeile 8: / Zeile 12: @@
-====== Datentypen, Encoding ======
+===== Datentypen, Encoding =====
-POST-Parameter werden mit dem MIME-Type <code>application/x-www-form-urlencoded</code>
+POST-Parameter werden mit dem MIME-Type ''application/x-www-form-urlencoded''
-formatiert und mit <code>UTF-8</code> kodiert übergeben.
+formatiert und mit ''UTF-8'' kodiert übergeben.
-Antworten werden als JSON (Mime-Type <code>application/json</code>) formatiert und
+Antworten werden als JSON (Mime-Type ''application/json'') formatiert und
-mit <code>UTF-8</code> kodiert übertragen.
+mit ''UTF-8'' kodiert übertragen.
-====== Verhalten im Fehlerfall ======
+===== Verhalten im Fehlerfall =====
+==== Genutzte HTTP-Statuscodes ====
-===== Genutzte HTTP-Statuscodes =====
+  *  ''300 Multiple Choices'': Mehrere Versionen der angeforderten Ressource verfügbar
+  *  ''301 Moved Permanently'': Zugriff ohne SSL mit Weiterleitung auf HTTPS
+  *  ''401 Unauthorized'': Authentifizierungsfehler
+  *  ''404 Not Found'': Resource nicht gefunden
+  *  ''405 Method Not Allowed'': Unzulässige HTTP-Methode
+  *  ''450 Rate Limit Exceeded'': Request-Limit wurde erreicht
+  *  ''451 Invalid Input'': Falsche oder fehlende Parameter
+  *  ''500 Internal Server Error'': Ein serverseitiger Fehler ist aufgetreten
+  *  ''503 Service Unavailable'': API ist auf Grund von Wartungsarbeiten temporär nicht erreichbar
-  *  <code>300 Multiple Choices</code>: Mehrere Versionen der angeforderten Ressource verfügbar
-  *  <code>301 Moved Permanently</code>: Zugriff ohne SSL mit Weiterleitung auf HTTPS
-  *  <code>401 Unauthorized</code>: Authentifizierungsfehler
-  *  <code>404 Not Found</code>: Resource nicht gefunden
-  *  <code>405 Method Not Allowed</code>: Unzulässige HTTP-Methode
-  *  <code>450 Rate Limit Exceeded</code>: Request-Limit wurde erreicht
-  *  <code>451 Invalid Input</code>: Falsche oder fehlende Parameter
-  *  <code>500 Internal Server Error</code>: Ein serverseitiger Fehler ist aufgetreten
-  *  <code>503 Service Unavailable</code>: API ist auf Grund von Wartungsarbeiten temporär nicht erreichbar
+==== Aufbau einer Antwort ====
-===== Aufbau einer Antwort =====
   *  Root-Objekt
-    *  <code>"error"</code>-Objekt mit folgenden Elementen
+    *  ''"error"''-Objekt mit folgenden Elementen
-      *  <code>"status"</code>: Integer, entspricht HTTP-Status
+      *  ''"status"'': Integer, entspricht HTTP-Status
-      *  <code>"code"</code>: Maschinenlesbare Bezeichnung des Fehlers
+      *  ''"code"'': Maschinenlesbare Bezeichnung des Fehlers
-      *  <code>"message"</code>:  Beschreibung des Fehlers
+      *  ''"message"'':  Beschreibung des Fehlers
-      *  <code>"invalid"</code>: Für 451, optional. Liste ungültiger Eingabeparameter
+      *  ''"invalid"'': Für 451, optional. Liste ungültiger Eingabeparameter
-        *  Beispiel: <code>["mileage", "fuel"]</code>
+        *  Beispiel: ''["mileage", "fuel"]''
-      *  <code>"missing"</code>: Für 451, optional. Liste fehlender Eingabeparameter
+      *  ''"missing"'': Für 451, optional. Liste fehlender Eingabeparameter
-        *  Beispiel: <code>["year", "month"]</code>
+        *  Beispiel: ''["year", "month"]''
-      *  <code>"options"</code>: Für 300: Assoziatives Array von Auswahlmöglichkeiten
+      *  ''"options"'': Für 300: Assoziatives Array von Auswahlmöglichkeiten
-        *  Beispiel: <code>'model' => ['ModelA', 'ModelB']</code>
+        *  Beispiel: '''model' => ['ModelA', 'ModelB']''
-      *  <code>"url"</code>: Für 300: URL-Template mit Platzhaltern für die in <code>options</code> gelisteten Möglichkeiten
+      *  ''"url"'': Für 300: URL-Template mit Platzhaltern für die in ''options'' gelisteten Möglichkeiten
-        *  Beispiel (gekürzt): <code>https://.../calculate/1234/abc?...&model={model}</code>
+        *  Beispiel (gekürzt): ''https://.../calculate/1234/abc?...&model={model}''
-===== Beispiel =====
+==== Beispiel ====
-<code>GET /brand/42
+<code>
+GET /brand/42
 </code>
-<code>{
+<code>
+{
     "error": {
         "status": 404,
@@ Zeile 68: / Zeile 74: @@
 </code>
-====== URLs ======
+===== URLs =====
-===== Allgemeines =====
+==== Allgemeines ====
-Prefix: <code>/api/v1</code>
+Prefix: ''/api/v1''
 Die folgenden URLs werden an den Prefix angehangen. Die zu verwendende HTTP-Methode zum Zugriff ist
@@ Zeile 83: / Zeile 88: @@
-===== Übersicht =====
+==== Übersicht ====
 Funktionen aus SoapServer2:
-  *  calcCar: <code>GET /calculate/{hsn}/{tsn}</code>
+  *  calcCar: ''GET /calculate/{hsn}/{tsn}''  (kostenpflichtig, wird gezählt und abgerechnet)
-  *  getColors: <code>GET /colors</code>
+  *  getColors: ''GET /colors''
-  *  getFeatureList: <code>GET /features</code>
+  *  getFeatureList: ''GET /features''
 Funktionen aus autofokus24Tree:
-  *  getMakes: <code>GET /brands</code>
+  *  getMakes: ''GET /brands''
-  *  getModels: <code>GET /brands/{brand_id}/models</code>
+  *  getModels: ''GET /brands/{brand_id}/models''
-  *  getSubmodels: <code>GET /models/{model_id}/submodels</code>
+  *  getSubmodels: ''GET /models/{model_id}/submodels''
-  *  getBuldtypes: <code>GET /submodels/{submodel_id}/bodies</code>
+  *  getBuildtypes: ''GET /submodels/{submodel_id}/bodies''
-  *  getMotors: <code>GET /submodels/{submodel_id}/bodies/{body_id}/engines</code>
+  *  getMotors: ''GET /submodels/{submodel_id}/bodies/{body_id}/engines''  (bedingt kostenpflichtig, falls kein Folgeaufruf von getFokusCodes erfolgt)
-  *  getFokuscodes: <code>GET /submodels/{submodel_id}/bodies/{body_id}/engines/{engine_id}/editions</code>
+  *  getFokuscodes: ''GET /submodels/{submodel_id}/bodies/{body_id}/engines/{engine_id}/editions''  (kostenpflichtig, wird gezählt und abgerechnet)
 Für eine spätere Version geplante Funktionen:
-  *  <code>GET /brands/{brand_id}</code>
+  *  ''GET /brands/{brand_id}''
-  *  <code>GET /models/{model_id}</code>
+  *  ''GET /models/{model_id}''
-  *  <code>GET /submodels/{submodel_id}</code>
+  *  ''GET /submodels/{submodel_id}''
-  *  <code>GET /submodels/{submodel_id}/bodies/{body_id}</code>
+  *  ''GET /submodels/{submodel_id}/bodies/{body_id}''
-  *  <code>GET /submodels/{submodel_id}/bodies/{body_id}/engines/{engine_id}</code>
+  *  ''GET /submodels/{submodel_id}/bodies/{body_id}/engines/{engine_id}''
-  *  <code>GET /submodels/{submodel_id}/bodies/{body_id}/engines/{engine_id}/editions/{edition_id}</code>
+  *  ''GET /submodels/{submodel_id}/bodies/{body_id}/engines/{engine_id}/editions/{edition_id}''
-===== GET /colors =====
+==== GET /colors ====
+=== Beschreibung ===
-==== Beschreibung ====
@@ Zeile 118: / Zeile 122: @@
-==== Beispiel ====
+=== Beispiel ===
-<code>GET /api/v1/colors
+<code>
+GET /api/v1/colors
 </code>
-<code>{
+<code>
+{
     "wht": "weiss",
     "red": "rot",
@@ Zeile 131: / Zeile 138: @@
 </code>
-===== GET /features =====
+==== GET /features ====
+=== Beschreibung ===
-==== Beschreibung ====
@@ Zeile 141: / Zeile 147: @@
-==== Beispiel ====
+=== Beispiel ===
-<code>GET /api/v1/features
+<code>
+GET /api/v1/features
 </code>
-<code>{
+<code>
+{
     "GAS": "Gasantrieb",
     "ELE": "Elektromotor",
@@ Zeile 154: / Zeile 163: @@
 </code>
-===== GET /brands =====
+==== GET /brands ====
-==== Beschreibung ====
+=== Beschreibung ===
@@ Zeile 164: / Zeile 172: @@
-==== Beispiel ====
+=== Beispiel ===
-<code>GET /api/v1/brands
+<code>
+GET /api/v1/brands
 </code>
-<code>{
+<code>
+{
     "brands": {
         "1": "Alfa Romeo",
@@ Zeile 180: / Zeile 191: @@
 </code>
-===== GET /brands/{brand_id}/models =====
+==== GET /brands/{brand_id}/models ====
+=== Beschreibung ===
-==== Beschreibung ====
@@ Zeile 191: / Zeile 201: @@
-==== Parameter ====
+=== Parameter ===
 In der URL übergeben:
-  *  <code>brand_id</code>: ID der Marke
+  *  ''brand_id'': ID der Marke
 Im Query-String übergeben:
-  *  <code>year</code>: Jahr der Erstzulassung
+  *  ''year'': Jahr der Erstzulassung
-  *  <code>month</code>: Monat der Erstzulassung
+  *  ''month'': Monat der Erstzulassung
-==== Fehler ====
+=== Fehler ===
-  *  <code>404 BRAND_NOT_FOUND</code>: Marke nicht gefunden
+  *  ''404 BRAND_NOT_FOUND'': Marke nicht gefunden
-==== Beispiel ====
+=== Beispiel ===
-<code>GET /api/v1/brands/37/models?year=2015&month=5
+<code>
+GET /api/v1/brands/37/models?year=2015&month=5
 </code>
-<code>{
+<code>
+{
     "models": {
         "850": "Amarok",
@@ Zeile 226: / Zeile 239: @@
 </code>
-===== GET /models/{model_id}/submodels =====
+==== GET /models/{model_id}/submodels ====
+=== Beschreibung ===
-==== Beschreibung ====
@@ Zeile 237: / Zeile 249: @@
-==== Parameter ====
+=== Parameter ===
 In der URL übergeben:
-  *  <code>model_id</code>: ID des Modells
+  *  ''model_id'': ID des Modells
 Im Query-String übergeben:
-  *  <code>year</code>: Jahr der Erstzulassung
+  *  ''year'': Jahr der Erstzulassung
-  *  <code>month</code>: Monat der Erstzulassung
+  *  ''month'': Monat der Erstzulassung
-==== Fehler ====
+=== Fehler ===
-  *  <code>404 MODEL_NOT_FOUND</code>: Modell nicht gefunden
+  *  ''404 MODEL_NOT_FOUND'': Modell nicht gefunden
-==== Beispiel ====
+=== Beispiel ===
-<code>GET /api/v1/models/864/submodels?year=2015&month=5
+<code>
+GET /api/v1/models/864/submodels?year=2015&month=5
 </code>
-<code>{
+<code>
+{
     "submodels": {
         "1191": "Modell ab 2010",
@@ Zeile 270: / Zeile 285: @@
 </code>
-===== GET /submodels/{submodel_id}/bodies =====
+==== GET /submodels/{submodel_id}/bodies ====
-==== Beschreibung ====
+=== Beschreibung ===
@@ Zeile 280: / Zeile 294: @@
-==== Parameter ====
+=== Parameter ===
 In der URL übergeben:
-  *  <code>submodel_id</code>: ID der Baureihe
+  *  ''submodel_id'': ID der Baureihe
 Im Query-String übergeben:
-  *  <code>year</code>: Jahr der Erstzulassung
+  *  ''year'': Jahr der Erstzulassung
-  *  <code>month</code>: Monat der Erstzulassung
+  *  ''month'': Monat der Erstzulassung
-==== Fehler ====
+=== Fehler ===
-  *  <code>404 SUBMODEL_NOT_FOUND</code>: Submodell nicht gefunden
+  *  ''404 SUBMODEL_NOT_FOUND'': Submodell nicht gefunden
-==== Beispiel ====
+=== Beispiel ===
-<code>GET /api/v1/submodels/1191/bodies?year=2015&month=5
+<code>
+GET /api/v1/submodels/1191/bodies?year=2015&month=5
 </code>
-<code>{
+<code>
+{
     "bodies": {
         "42": {
@@ Zeile 319: / Zeile 336: @@
 </code>
-===== GET /submodels/{submodel_id}/bodies/{body_id}/engines =====
+==== GET /submodels/{submodel_id}/bodies/{body_id}/engines ====
+=== Beschreibung ===
-==== Beschreibung ====
@@ Zeile 330: / Zeile 346: @@
-==== Parameter ====
+=== Parameter ===
 In der URL übergeben:
-  *  <code>submodel_id</code>: ID der Baureihe
+  *  ''submodel_id'': ID der Baureihe
-  *  <code>body_id</code>: ID der Aufbauvariante
+  *  ''body_id'': ID der Aufbauvariante
 Im Query-String übergeben:
-  *  <code>year</code>: Jahr der Erstzulassung
+  *  ''year'': Jahr der Erstzulassung
-  *  <code>month</code>: Monat der Erstzulassung
+  *  ''month'': Monat der Erstzulassung
-==== Fehler ====
+=== Fehler ===
-  *  <code>404 SUBMODEL_NOT_FOUND</code>: Submodell nicht gefunden
+  *  ''404 SUBMODEL_NOT_FOUND'': Submodell nicht gefunden
-  *  <code>404 BODY_NOT_FOUND</code>: Aufbau nicht gefunden
+  *  ''404 BODY_NOT_FOUND'': Aufbau nicht gefunden
-==== Beispiel ====
+=== Beispiel ===
-<code>GET /api/v1/submodels/1191/bodies/42/engines?year=2015&month=5
+<code>
+GET /api/v1/submodels/1191/bodies/42/engines?year=2015&month=5
 </code>
-<code>{
+<code>
+{
     "engines": {
         "6590": {
@@ Zeile 378: / Zeile 397: @@
 </code>
-===== GET /submodels/{submodel_id}/bodies/{body_id}/engines/{engine_id}/editions =====
+==== GET /submodels/{submodel_id}/bodies/{body_id}/engines/{engine_id}/editions ====
-==== Beschreibung ====
+=== Beschreibung ===
@@ Zeile 389: / Zeile 408: @@
-==== Parameter ====
+=== Parameter ===
 In der URL übergeben:
-  *  <code>submodel_id</code>: ID der Baureihe
+  *  ''submodel_id'': ID der Baureihe
-  *  <code>body_id</code>: ID der Aufbauvariante
+  *  ''body_id'': ID der Aufbauvariante
-  *  <code>engine_id</code>: ID des Motors
+  *  ''engine_id'': ID des Motors
 Im Query-String übergeben:
-  *  <code>year</code>: Jahr der Erstzulassung
+  *  ''year'': Jahr der Erstzulassung
-  *  <code>month</code>: Monat der Erstzulassung
+  *  ''month'': Monat der Erstzulassung
-==== Fehler ====
+=== Fehler ===
-  *  <code>404 SUBMODEL_NOT_FOUND</code>: Submodell nicht gefunden
+  *  ''404 SUBMODEL_NOT_FOUND'': Submodell nicht gefunden
-  *  <code>404 BODY_NOT_FOUND</code>: Aufbau nicht gefunden
+  *  ''404 BODY_NOT_FOUND'': Aufbau nicht gefunden
-  *  <code>404 ENGINE_NOT_FOUND</code>: Motor nicht gefunden
+  *  ''404 ENGINE_NOT_FOUND'': Motor nicht gefunden
-==== Beispiel ====
+=== Beispiel ===
-<code>GET /api/v1/submodels/1191/bodies/42/engines/6590/editions?year=2015&month=5
+<code>
+GET /api/v1/submodels/1191/bodies/42/engines/6590/editions?year=2015&month=5
 </code>
-<code>{
+<code>
+{
     "editions": {
         "84795": {
@@ Zeile 423: / Zeile 445: @@
             "hsn": "0603",
             "tsn": "AQH",
-            "other_tsns": [
+            "other_tsns": []
-                "AQH",
-                "AYF",
-                "BDC"
-            ]
         },
         "85195": {
@@ Zeile 433: / Zeile 451: @@
             "hsn": "0603",
             "tsn": "AYF",
-            "other_tsns": [
+            "other_tsns": []
-                "AQH",
-                "AYF",
-                "BDC"
-            ]
         },
         ...
@@ Zeile 444: / Zeile 458: @@
 </code>
-===== GET /calculate/{hsn}/{tsn} =====
+==== GET /calculate/{hsn}/{tsn} ====
+=== Beschreibung ===
-==== Beschreibung ====
 Gibt zu einer angegebenen HSN und TSN entsprechende Preisschätzungen, Ausstattung und weitere
-Grundinformationen zurück. Da der Parameter <code>free_text</code> sehr lang werden kann, darf diese Funktion
+Grundinformationen zurück. Da der Parameter ''free_text'' sehr lang werden kann, darf diese Funktion
-auch per <code>POST</code> abgerufen werden.
+auch per ''POST'' abgerufen werden.
-==== Parameter ====
+=== Parameter ===
@@ Zeile 465: / Zeile 478: @@
 In der URL übergeben:
-  *  <code>hsn</code>: Herstellerschlüsselnummer
+  *  ''hsn'': Herstellerschlüsselnummer
-  *  <code>tsn</code>: Typschlüsselnummer
+  *  ''tsn'': Typschlüsselnummer
 Im Query-String übergeben:
-  *  <code>year</code>: Jahr der Erstzulassung
+  *  ''year'': Jahr der Erstzulassung
-  *  <code>month</code>: Monat der Erstzulassung
+  *  ''month'': Monat der Erstzulassung
-  *  <code>mileage</code>: Laufleistung in km, ehemals <code>miles</code>
+  *  ''mileage'': Laufleistung in km, ehemals ''miles''
   *  Optionale Parameter:
-    *  <code>free_text</code>: Beliebiger Fließtext zur Auswertung mit Einfluss auf die Bewertung, ehemals <code>fuzzyText</code>
+    *  ''free_text'': Beliebiger Fließtext zur Auswertung mit Einfluss auf die Bewertung, ehemals ''fuzzyText''
-    *  <code>model</code>: Modellbezeichnung
+    *  ''model'': Modellbezeichnung
-    *  <code>edition</code>: Ausstattungsvariante / Sondermodell, ehemals <code>specialModel</code>
+    *  ''edition'': Ausstattungsvariante / Sondermodell, ehemals ''specialModel''; die Schreibweise des Sondermodells ist der Funktion ''.../editions'' zu entnehmen
-    *  <code>equipment</code>: Aufzählung der Ausstattungsmerkmale, ehemals <code>featureList</code>
+    *  ''equipment'': Aufzählung der Ausstattungsmerkmale, ehemals ''featureList''
-    *  <code>color</code>: Kurzbezeichnung der Farbe
+    *  ''color'': Kurzbezeichnung der Farbe
-    *  <code>power</code>: Motorleistung in KW
+    *  ''power'': Motorleistung in KW
-    *  <code>fuel</code>: Kraftstoff
+    *  ''fuel'': Kraftstoff
-    *  <code>body</code>: Aufbau, ehemals <code>buildType</code>
+    *  ''body'': Aufbau, ehemals ''buildType''
-    *  <code>doors</code>: Anzahl Türen, ehemals <code>doorCount</code>
+    *  ''doors'': Anzahl Türen, ehemals ''doorCount''
-    *  <code>dealer_type</code>: Unternehmensart, ehemals <code>dealerSize</code>
+    *  ''dealer_type'': Unternehmensart, ehemals ''dealerSize''
-    *  <code>price_range</code>: durchschnittliche Preisklasse des Händlers, ehemals <code>priceClass</code>
+    *  ''price_range'': durchschnittliche Preisklasse des Händlers, ehemals ''priceClass''
-    *  <code>stock_size</code>: durchschnittlicher Fahrzeugbestand, ehemals <code>carVolume</code>
+    *  ''stock_size'': durchschnittlicher Fahrzeugbestand, ehemals ''carVolume''
-    *  <code>guarantees</code>: üblicherweise angebotene Garantieleistungen, ehemals <code>garantieValue</code>
+    *  ''guarantees'': üblicherweise angebotene Garantieleistungen, ehemals ''garantieValue''
-    *  <code>idle_time</code>: Standzeit zur Berechnung der Verkaufswahrscheinlichkeiten in <code>sales_probability</code>, ehemals <code>monthWaitForSell</code>
+    *  ''idle_time'': Standzeit zur Berechnung der Verkaufswahrscheinlichkeiten in ''sales_probability'', ehemals ''monthWaitForSell''
-    *  <code>yearly_mileage</code>: Jährliche Laufleistung in km, ehemals <code>milesPerYear</code>
+    *  ''yearly_mileage'': Jährliche Laufleistung in km zur Berechnung der Restwertprognose in ''degeneration'', ehemals ''milesPerYear''
-    *  <code>estimated_life</code>: Geplante Nutzungsdauer in Jahren, ehemals <code>usageYearCount</code>
+    *  ''estimated_life'': Geplante Nutzungsdauer in Jahren zur Berechnung der Restwertprognose in ''degeneration'', ehemals ''usageYearCount''
-==== Fehler ====
+=== Fehler ===
-  *  <code>300 MULTIPLE_MODELS</code>: Mehrere zutreffende Modelle gefunden
+  *  ''300 MULTIPLE_MODELS'': Mehrere zutreffende Modelle gefunden
-  *  <code>404 NOT_FOUND</code>: HSN oder TSN nicht gefunden
+  *  ''404 NOT_FOUND'': HSN oder TSN nicht gefunden
-  *  <code>404 NOT_FOUND_IN_TIMESPAN</code>: HSN oder TSN im angegebenen Zeitraum nicht gefunden
+  *  ''404 NOT_FOUND_IN_TIMESPAN'': HSN oder TSN im angegebenen Zeitraum nicht gefunden
 Für letzteren Fehler werden ein oder zwei zusätzliche Felder zurückgegeben:
-<code>build_since</code> und <code>build_until</code>. Beispiel:
+''build_since'' und ''build_until''. Beispiel:
-<code>{
+<code>
+{
     "error": {
         "status": 404,
@@ Zeile 513: / Zeile 527: @@
 </code>
-==== Beispiel ====
+=== Beispiel ===
-<code>GET /api/v1/calculate/0603/aqh?year=2015&month=5&mileage=10000&idle_time=2&color=wht
+<code>
+GET /api/v1/calculate/0603/aqh?year=2015&month=5&mileage=10000&idle_time=2&color=wht
 </code>
-<code>[
+<code>
+[
     {
         "hsn": "0603",
@@ Zeile 559: / Zeile 576: @@
             "19250": 68,
             ...
-        }  # Ehemals "avgSellingTimes"
+        },  # Ehemals "avgSellingTimes"
+        "degeneration": [
+,
+,
+,
+            ...
+        ]
     },
     ...
-</code> ]
+]
+</code>

Autofokus24 Wiki

Benutzer-Werkzeuge

Webseiten-Werkzeuge

Unterschiede

Seiten-Werkzeuge