Frage zu API-Design

xrax

Erfahrenes Mitglied
Hallo zusammen,

ich bauen gerade ein Schnittstelle mittels einem JAVA-Servlet.
Über diese Schnittstelle sollen die Kunden Daten abrufen können.
Der Kunde gibt also im Querystring seine Zugangsdaten, die gewünschte Datenart und welche Daten er möchte an.
Sieht dann zB so aus:
http://123.345.456.789:8080/API?callid=GET_ADRESS&user=foo&pass=bar&Müller;|Maier;|Schmidt;|

Er möchte also die Adressen von Müller,Maier und Schmidt.

Er sollte auch weitere Parameter angeben können. Sähe dann vielleicht so aus ......&para1;Müller;|para1;Maier;|para1;Schmidt;|

Ich habe nun aber Probleme mit der Angabe bzw. der Übermittlung der Datenanfrage (......&para1;Müller;|para1;Maier;|para1;Schmidt;|)
Gibt es hierzu einen etablierten Standart wie die Daten zu übertragen sind ? Vor allem bezügl. der Trennzeichen ";" und "|".

Würde mich über Info freuen

Beste Grüße
xrax
 

CookieBuster

Erfahrenes Mitglied
json ist ein sehr praktisches Format um eine Datenschnittstelle dieser Art zu erstellen, wird auch sehr häufig verwendet.
 

xrax

Erfahrenes Mitglied
Hm,- verstehe ich nicht. Das Servlet liefer in verschiedenen Formaten (auch JSON) die Daten an den Kunden. Aber wie stellt er (der Kunde) die Anfrage in JSON an ein Servlet ?
 

CookieBuster

Erfahrenes Mitglied
Normalerweise werden die Anfragen mit einer URL gemacht um dann eine json-Antwort zu erhalten. Bei den meisten Schnittstellen kann man aus diesem Grund die Inhalte auch per Browser abfragen und einsehen.
 

xrax

Erfahrenes Mitglied
Naja, aber das war doch meine Frage :). Wie Du an meinem Anfangspost siehst frage ich nach einem Standard für die Anfrage.
Trotzdem danke für die Antwort.
 

Bratkartoffel

gebratene Kartoffel
Premium-User
Hi,

Generell würde ich die diversen Parameter als GET-Parameter mit der Anfrage mitschicken. Wenn möglich das ganze auch noch Restfull, so dass das ganze einigermaßen leserlich bleibt und die Trennung der Funktionen im Backend einfacher ist. (zum Beispiel mit spring RequestMapping)
Code:
/api/users/${userId}/details
/api/users/find?name=Hans Mueller

Falls du im Backend eine List brauchst, dann kannst du die Parameter auch so angeben:
Code:
...&multiField[0]=Hans&multiField[1]=Sepp&multiField[2]=Ludwig...

Vorteil bei der Lösung ist, dass du die Schnittstelle einfach mit einem Browser und der URL direkt testen kannst. Nachteil ist, dass die URL schnell sehr lang und unleserlich werden kann.

Wenn du allerdings viele Parameter zum senden hast kann es sein, dass deine URL dadurch zu lang wird. Hier kannst du die Daten auch wie bei einem Formular im Body der Anfrage schicken. Hierbei bist du vom Format her frei, je nachdem was dir besser gefällt kannst du die Daten dann URL-Encoded oder als JSON schicken. Persönlich würde ich wegen der hohen Flexiblität eher zu JSON tendieren.

Aber abseits der "Art" der Datenübermittlung:
Aus eigener Erfahrung kann dir nur raten die API so präzise und simpel wie möglich zu spezifizieren. Nicht einfach darauf los programmieren, sondern erstmal sauber eine kleine Dokumentation erstellen an der du dich dann gleich orientieren kannst.
  • Welche Schnittstellen gibt es und welche Daten erwarten / liefern diese? (Long, Double, Wertebereich)
  • Welche Anfrage-Parameter sind optional, welche mandatory?
  • Wie werden Fehler der Schnittstelle zurückgeliefert?
  • Welche Daten werden bewusst (mit Begründung) nicht zur Verfügung gestellt? (Beispiel: "GET /api/users/1", Passwort sollte nicht geliefert werden)
  • Wie bildest du die fachlichen Anforderungen auf die Schnittstelle ab, welche Funktion verbirgt sich hinter welchem Pfad? (Beispiel: "POST /api/users/1" = Update, "GET /api/users/1" = Details abholen)
  • Wie sieht es mit Zugriffsrechten aus? (Benutzerrechte? Replay-Angriffe? Ungültige Daten?)
  • Kannst du die API selbst komplett testen? Wenn ja, dann schreibe Testfälle.
Wenn du zu diesen Punkten auch noch eine Begründung für die Entscheidung hinterlegst dann sollte einer guten API nichts im Wege stehen :)

Grüße,
BK