Loading…

Blog

Viel Spass beim Lesen, vielleicht findest Du ja ein paar nützliche Informationen
Los geht's

Best Practice – REST API

Web-APIs sind im letzten Jahr ein sehr wichtiges Thema geworden. Wir arbeiten jeden Tag mit verschiedenen Backend-Systemen und wissen daher um die Bedeutung eines sauberen API-Designs.

Typischerweise verwenden wir ein RESTful Design für unsere Web APIs. Das Konzept von REST besteht darin, die API-Struktur in logische Ressourcen aufzuteilen. Es werden die HTTP-Methoden GET, DELETE, POST und PUT verwendet, um mit den Ressourcen zu arbeiten.

Dies sind 10 Best Practices für das Design einer sauberen RESTful-API:

1. Substantive, aber keine Verben verwenden

Für ein einfaches Verständnis verwenden Sie diese Struktur für jede Ressource:

Resource GET
lesen
POST
erstellen
PUT
aktualisieren
DELETE
/orders liefert eine Liste von Bestellungen Anlegen einer neuen Bestellung Massen Änderung von Bestellungen Löschen von Bestellungen
/orders/123 Liefert die Daten einer einzelnen Bestellung Method not allowed (405) Änderung an einer Einzelnen Bestellung Lösche eine einzelne Bestellung

Keine Verben verwenden:
/getAllOrders
/createNewOrder
/deleteAllCanceledOrders

2. GET Methode und Abfrageparameter sollten den Zustand nicht verändern.

Verwenden Sie PUT-, POST- und DELETE-Methoden anstelle der GET-Methode, um den Zustand zu ändern.

Verwenden Sie nicht GET für Zustandsänderungen:
GET /orders/123?activate oder
GET /orders/123/activate

3. Plural-Substantive verwenden

Verwechseln Sie nicht Singular- und Pluralsubstantive. Halten Sie es einfach und verwenden Sie nur Pluralnomen für alle Ressourcen.

/orders anstelle von /order
/users anstelle von /user
/settings anstelle von /setting


4. Sub-Ressourcen für Beziehungen verwenden

Wenn eine Ressource mit einer anderen Ressource in Beziehung steht, verwenden Sie Sub-Ressourcen.

GET /orders/123/customers/ Liefert den Kunden einer Bestellung
GET /orders/123/items/ Liefert die Artikelpositionen einer Bestellung
GET /orders/123/items/3 Liefert die Artikelposition 3 einer Bestellung

5. HTTP-Header für Serialisierungsformate verwenden

Beide, Client und Server, müssen wissen, welches Format für die Kommunikation verwendet wird. Das Format muss im HTTP-Header angegeben werden.

„Content-Type“ definiert das Anfrageformat.
„Accept“ definiert eine Liste von akzeptablen Antwortformaten.

6. HATEOAS verwenden

Hypermedia as the Engine of Application State (Hypermedia als Motor des Anwendungszustands) ist ein Prinzip, dass Hypertext-Links verwendet werden sollten, um eine bessere Navigation durch die API zu schaffen.

{ 
"id": 123,
"provider": "webshop",
"created": "2020-12-17 07:34:02",
"customer": {
"firstname": "Kai",
"lastname": "Mustermann",
"address": [
{
"type": "billing",
"street": "Musterstrasse 1",
....
}
]
},
"items": [
{
"id": 26789,
"title": "Artikel XY",
...
},
{
"id": 18767,
"title": "Artikel AB",
...
},
]

}

 

7. Filterung, Sortierung, Feldauswahl und Paging für Sammlungen bereitstellen

Filtern:

Verwenden Sie einen eindeutigen Abfrageparameter für alle Felder oder eine Abfragesprache für die Filterung.

GET /orders?provider=webshop Liefert eine Liste von Bestellungen, die über den webshop angelegt wurden
GET /orders?created<=2019 Liefert eine Liste von Bestellungen die vor 2019 angelegt wurden 

Sorting:

Aufsteigende und absteigende Sortierung über mehrere Felder zulassen.

GET /orders?sort=-created,+provider

Dies gibt eine Liste von Bestellungen zurück, die nach absteigenden Erstellungsdatum und aufsteigenden Provider sortiert ist.

Feldauswahl:

Mobile Clients zeigen nur einige wenige Attribute in einer Liste an. Sie benötigen nicht alle Attribute einer Ressource. Geben Sie dem API-Konsumenten die Möglichkeit, zurückgegebene Felder auszuwählen. Dadurch wird auch der Netzwerkverkehr reduziert und die Nutzung der API beschleunigt.

GET /orders?fields=provider,id,created

Paging

Verwenden Sie Limit und Offset. Das ist flexibel für den Benutzer und in führenden Datenbanken üblich. Die Voreinstellung sollte limit=20 und offset=0 sein

GET /orders?offset=10&limit=5

Um die Gesamteinträge an den Benutzer zurückzusenden, verwenden Sie den benutzerdefinierten HTTP-Header: X-Total-Count.

Links zur nächsten oder vorherigen Seite sollten ebenfalls im HTTP-Header Link angegeben werden. Es ist wichtig, diesen Link-Header-Werten zu folgen, anstatt eigene URLs zu konstruieren.

Link: <https://www.mypage.com/sample/api/v1/orders?offset=15&limit=5>; rel=“next“,

<https://www.mypage.com/sample/api/v1/orders?offset=50&limit=3>; rel="last",
<https://www.mypage.com/sample/api/v1/orders?offset=0&limit=5>; rel="first",
<https://www.mypage.com/sample/api/v1/orders?offset=5&limit=5>; rel="prev",

8. Version Ihrer API

Machen Sie die API-Version obligatorisch und veröffentlichen Sie keine unversionierte API. Verwenden Sie eine einfache Ordnungszahl und vermeiden Sie Punktnotation wie z. B. 2.5.

Wir verwenden die Url für die API-Versionierung, die mit dem Buchstaben „v“ beginnt

/sample/api/v1

9. Behandlung von Fehlern mit HTTP-Statuscodes

Es ist schwer, mit einer API zu arbeiten, die die Fehlerbehandlung ignoriert. Die reine Rückgabe eines HTTP 500 mit einem Stacktrace ist nicht sehr hilfreich.

HTTP-Statuscodes verwenden

Der HTTP-Standard bietet über 70 Statuscodes, um die Rückgabewerte zu beschreiben. Wir brauchen sie nicht alle, aber es sollte mindestens ein Satz von 10 verwendet werden.

200 – OK – Eyerything is working
201 – OK – New resource has been created
204 – OK – The resource was successfully deleted

304 – Not Modified – The client can use cached data

400 – Bad Request – The request was invalid or cannot be served. The exact error should be explained in the error payload. E.g. „The JSON is not valid“
401 – Unauthorized – The request requires an user authentication
403 – Forbidden – The server understood the request, but is refusing it or the access is not allowed.
404 – Not found – There is no resource behind the URI.
422 – Unprocessable Entity – Should be used if the server cannot process the enitity, e.g. if an image cannot be formatted or mandatory fields are missing in the payload.

500 – Internal Server Error – API developers should avoid this error. If an error occurs in the global catch blog, the stracktrace should be logged and not returned as response.

Fehler-Payloads verwenden

Alle Ausnahmen sollten in einem Error-Payload abgebildet werden. Hier ist ein Beispiel, wie ein JSON-Payload aussehen könnte.

{
  "errors": [
  {
    "userMessage": "Sorry, the requested resource does not exist",
    "internalMessage": "No order found in the database",
    "code": 21,
    "more info": "<https://www.mypage.com/sample/api/v1/errors/21
  }
]

}

 

10. Überschreiben der HTTP-Methode zulassen

Einige Proxys unterstützen nur die Methoden POST und GET. Um eine RESTful-API mit diesen Einschränkungen zu unterstützen, benötigt die API eine Möglichkeit, die HTTP-Methode außer Kraft zu setzen.

Verwenden Sie den benutzerdefinierten HTTP-Header X-HTTP-Method-Override, um die POST-Methode außer Kraft zu setzen.

Schreibe einen Kommentar