Tag: API

Da REST API in letzter Zeit recht populär geworden sind habe ich ein paar grundlegende Richtlinien für gutes REST API Design zusammen getragen.

Resources & Operationen

Eine Resource ist eine Entität auf der verschieden Operationen ausgeführt werden könne.
Eine Resource repräsentiert ein Objekt wie User, Adressen, Logeinträge.

Folgende Besipiel zeigt die Operationen auf eine User Resource:

GET         /users/      – holt alle User
POST      /users/       – erzeugt einen neuen User
PUT        /users/{id} – ändert die bestehende Resource
GET        /users/{id} – hole die Resource eines Users
DELETE  /users/{id} – löscht die Resource eines Users

Eine Resource kann Sub Resourcen haben:

/users/{id}/adresses/{id}

Parameter

URL Parameter
Normalerweise der Pfad zur Resource.

URL Query Parameter
Für einfach Parameter, in der Regel Filter oder Paginierung auf GET Anfragen, z.b. um eine Collection zu filtern.

HTTP Body Parameter
Auch Payload genannt, um JSON Daten zu übergeben, über POST und PUT hier wird dann im Header der Content-Type: application/json übergeben.

HTTP Header
Werden in der Regel für Token oder CorelationId un ähnliches verwenden, nicht aber für Resourcen.

Bennenung von Resourcen

• Resourcen sind immer im Plural
• Hierachien werden durch Slashes “/” getrennt
• Kleingeschreibung ist bevorzugt
• “-” sollen verwendet werden und kein  “_”
• keine File Endungen in URL
• Eine Resource ist IMMER ein Nomen und NIE ein Verb.

URL Struktur

Adresse
http://hostame.de

Base Path
/produktName/api/ oder nur api/

Resource Path
/users/

Fehlerhandling

Fehler werden in der Regel mit http Status Codes behandelt, ein richtiger Umgang mit diesen Status Codes erleichtert dem Konsumenten
der Umgang mit der API. Hier eine lIst der gebräuchlichsten Error Codes:

200 OK
201 Created
202 Accepted
204 No Content
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
409 Conflict

Wem das nicht reicht findet hier eine komplette Liste:
https://de.wikipedia.org/wiki/HTTP-Statuscode

Zusätzlich zum Error Code sollte eine JSON Message zurückgeben.

{
"File not found": "User does not exist"
}

HATEOS

Hypermedia as the Engine of Application State
in ein Prinzip, das auf Hyperlinks zur besseren Navigation durch die API setzt.

{
   "id":12,
   "name":"Torsten",
   "adresses":[
      {
         "id":"23",
         "street":"Meine Strasse 12",
         "links":[
            {
               "rel":"self",
               "href":"/api/users/12/adresses/23"
            }
         ]
      }
   ]
}

Man muss meiner Meinung nach allerdings sagen, dass dieses Konzept eher eine akademisches ist und in der Praxis eher hinderlich ist als das es hilft. Die Implementierung ist sowohl auf Client wie auf Server Seite deutlich aufwändiger ohne einen wirklichen Nutzen zu haben.

Controller/Action

Da die meisten Anwendungen nicht rein Resourcen orientiert sind oder sein können, sollten Operation, die nicht einer Resource entsprechen
deutlich kenntlich gemmacht werden.
Man kann Verben verenden um klar zu machen das ist keine Resource:

• validateUser
• calculateLoanCondition
• activeAllUsers

Diese sollten dann der entprechende Resource zugeordnet werden und immer POST verwenden:

POST /users/validateUser