HTTP
HTTP für APIs

Bemerkungen

Erstellen Sie eine Ressource

Nicht jeder ist sich einig, was die semantisch korrekte Methode zur Ressourcenerstellung ist. Daher kann Ihre API POST oder PUT Anforderungen annehmen oder eine der beiden.

Der Server sollte mit 201 Created antworten, wenn die Ressource erfolgreich erstellt wurde. Wählen Sie den am besten geeigneten Fehlercode, falls nicht.

Wenn Sie beispielsweise eine API zum Erstellen von Mitarbeiterdatensätzen bereitstellen, könnte die Anforderung / Antwort folgendermaßen aussehen:

POST /employees HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "name": "Charlie Smith",
    "age": 38,
    "job_title": "Software Developer",
    "salary": 54895.00
}

HTTP/1.1 201 Created
Location: /employees/1/charlie-smith
Content-Type: application/json

{
    "employee": {
        "name": "Charlie Smith",
        "age": 38,
        "job_title": "Software Developer",
        "salary": 54895.00
        "links": [
            {
                "uri": "/employees/1/charlie-smith",
                "rel": "self",
                "method": "GET"
            },
            {
                "uri": "/employees/1/charlie-smith",
                "rel": "delete",
                "method": "DELETE"
            },
            {
                "uri": "/employees/1/charlie-smith",
                "rel": "edit",
                "method": "PATCH"
            }
        ]
    },
    "links": [
        {
            "uri": "/employees",
            "rel": "create",
            "method": "POST"
        }
    ]
}

Durch das Einbinden der links JSON-Felder in die Antwort kann der Client auf eine Ressource zugreifen, die sich auf die neue Ressource und die gesamte Anwendung bezieht, ohne deren URIs oder Methoden zuvor kennen zu müssen.

Bearbeiten Sie eine Ressource

Das Bearbeiten oder Aktualisieren einer Ressource ist ein allgemeiner Zweck für APIs. Edits kann durch Senden entweder dadurch erreicht werden , POST , PUT oder PATCH - Anfragen an die jeweiligen Ressource. Obwohl es dem POST erlaubt ist, Daten an die vorhandene Darstellung einer Ressource anzuhängen, wird empfohlen, entweder PUT oder PATCH da diese eine explizitere Semantik vermitteln.

Ihr Server sollte mit 200 OK antworten, wenn das Update durchgeführt wurde, oder 202 Accepted falls es noch nicht angewendet wurde. Wählen Sie den am besten geeigneten Fehlercode, falls dieser nicht abgeschlossen werden kann.

Vollständige Updates

PUT hat die Semantik, die aktuelle Darstellung durch die in der Anforderung enthaltene Nutzlast zu ersetzen. Wenn die Payload nicht denselben Repräsentationstyp wie die aktuelle Repräsentation der zu aktualisierenden Ressource aufweist, kann der Server entscheiden, welcher Ansatz gewählt wird. RFC7231 definiert, dass der Server entweder kann

• Konfigurieren Sie die Zielressource neu, um den neuen Medientyp wiederzugeben
• Wandeln Sie die PUT-Darstellung in ein Format um, das mit dem der Ressource übereinstimmt, bevor Sie sie als neuen Ressourcenstatus speichern
• Ablehnen die Anforderung mit einer 415 Unsupported Media Type unterstütztem 415 Unsupported Media Type Antwort , den anzeigt , dass die Zielressource zu einem bestimmten (set) von Medientypen beschränkt ist.

Eine Basisressource mit einer JSON- HAL- Darstellung wie ...

{
    "name": "Charlie Smith",
    "age": 39,
    "job_title": "Software Developer",
    "_links": {
        "self": { "href": "/users/1234" },
        "employee": { "href": "http://www.acmee.com" },
        "curies": [{ "name": "ea", "href": "http://www.acmee.com/docs/rels/{rel}", templated": true}],
        "ea:admin": [
            "href": "/admin/2",
            "title": "Admin"
        ]
    }
}

... erhält möglicherweise eine Aktualisierungsanfrage

PUT /users/1234 HTTP/1.1
Host: http://www.acmee.com
Content-Type: "application/json; charset=utf-8"
Content-Length: 85
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)

{
    "name": "Charlie Gold-Smith",
    "age": 40,
    "job_title": "Senior Software Developer"
}

Der Server kann jetzt den Status der Ressource durch den angegebenen Anforderungshauptteil ersetzen und auch den Inhaltstyp von application/hal+json in application/json ändern oder die JSON-Nutzdaten in eine JSON-HAL-Darstellung konvertieren und dann den Inhalt der Ressource ersetzen mit dem transformierten oder lehnen Sie die Aktualisierungsanforderung aufgrund eines nicht anwendbaren Medientyps mit einer Antwort vom Typ 415 Unsupported Media Type Medientyp ab.

Es besteht ein Unterschied, ob Sie den Inhalt direkt ersetzen oder zuerst die Repräsentation in das definierte Repräsentationsmodell umwandeln und dann den vorhandenen Inhalt durch den transformierten ersetzen. Eine nachfolgende GET Anforderung gibt die folgende Antwort auf einen direkten Ersatz zurück:

GET /users/1234 HTTP/1.1
Host: http://www.acmee.com
Accept-Encoding: gzip, deflate
Accept-Language: en-us
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)
ETag: "e0023aa4e"

{
    "name": "Charlie Gold-Smith",
    "age": 40,
    "job_title": "Senior Software Developer"
}

Während der Transformations- und dann Wiederherstellungsansatz wird die folgende Darstellung zurückgegeben:

GET /users/1234 HTTP/1.1
Host: http://www.acmee.com
Accept-Encoding: gzip, deflate
Accept-Language: en-us
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)
ETag: e0023aa4e

{
    "name": "Charlie Gold-Smith",
    "age": 40,
    "job_title": "Senior Software Developer",
    "_links": {
        "self": { "href": "/users/1234" },
        "employee": { "href": "http://www.acmee.com" },
        "curies": [{ "name": "ea", "href": "http://www.acmee.com/docs/rels/{rel}", templated": true}],
        "ea:admin": [
            "href": "/admin/2",
            "title": "Admin"
        ]
    }
}

Nebenwirkungen

Beachten Sie, dass PUT Nebenwirkungen haben darf, obwohl es als idempotenter Vorgang definiert ist! Dies ist in RFC7231 als dokumentiert

Eine PUT-Anforderung, die auf die Zielressource angewendet wird, kann Nebenwirkungen auf andere Ressourcen haben . Beispielsweise kann ein Artikel einen URI zum Identifizieren der "aktuellen Version" (eine Ressource) haben, der von den URIs, die jede bestimmte Version identifizieren, getrennt ist (verschiedene Ressourcen, die an einem Punkt den gleichen Status wie die aktuelle Versionsressource hatten). Bei einer erfolgreichen PUT-Anforderung für den URI "Aktuelle Version" kann daher zusätzlich zur Änderung des Status der Zielressource eine neue Versionsressource erstellt werden. Außerdem können Verknüpfungen zwischen den zugehörigen Ressourcen hinzugefügt werden.

Das Erstellen zusätzlicher Protokolleinträge wird normalerweise nicht als Nebeneffekt betrachtet, da dies sicherlich kein Status einer Ressource im Allgemeinen ist.

Teilaktualisierungen

RFC7231 erwähnt dies bezüglich Teilaktualisierungen :

Partial Inhaltsaktualisierungen sind möglich , indem eine separat identifiziert Ressource mit Targeting - Zustand, der einen Teil der größeren Ressource überlappt, oder durch eine andere Methode , die (beispielsweise das Verfahren in PATCH definiert für die partielle Updates speziell definiert wurde RFC5789 ).

Teilaktualisierungen können daher in zwei Varianten durchgeführt werden:

• Lassen Sie eine Ressource mehrere kleinere Subressourcen einbetten und aktualisieren Sie statt der gesamten Ressource nur eine entsprechende PUT über PUT
• Verwenden Sie PATCH und PATCH den Server an, was aktualisiert werden soll

Teilaktualisierung mit überlappendem Status

Wenn eine Benutzerrepräsentation aufgrund einer Verschiebung eines Benutzers an einen anderen Ort teilweise aktualisiert werden muss, anstatt den Benutzer direkt zu aktualisieren, sollte die zugehörige Ressource direkt aktualisiert werden, was eine teilweise Aktualisierung der Benutzerrepräsentation widerspiegelt.

Vor dem Umzug hatte ein Benutzer die folgende Darstellung

GET /users/1234 HTTP/1.1
Host: http://www.acmee.com
Accept: application/hal+json; charset=utf-8
Accept-Encoding: gzip, deflate
Accept-Language: en-us
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)
ETag: "e0023aa4e"

{
    "name": "Charlie Gold-Smith",
    "age": 40,
    "job_title": "Senior Software Developer",
    "_links": {
        "self": { "href": "/users/1234" },
        "employee": { "href": "http://www.acmee.com" },
        "curies": [{ "name": "ea", "href": "http://www.acmee.com/docs/rels/{rel}", templated": true}],
        "ea:admin": [
            "href": "/admin/2",
            "title": "Admin"
        ]
    },
    "_embedded": {
        "ea:address": {
            "street": "Terrace Drive, Central Park",
            "zip": "NY 10024"
            "city": "New York",
            "country": "United States of America",
            "_links": {
                "self": { "href": "/address/abc" },
                "google_maps": { "href": "http://maps.google.com/?ll=40.7739166,-73.970176" }
            }
        }
    }
}

Wenn der Benutzer an einen neuen Standort wechselt, aktualisiert er seine Standortinformationen wie folgt:

PUT /address/abc HTTP/1.1
Host: http://www.acmee.com
Content-Type: "application/json; charset=utf-8"
Content-Length: 109
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)

{
    "street": "Standford Ave",
    "zip": "CA 94306",
    "city": "Pablo Alto",
    "country": "United States of America"
}

Mit der Transformations-vor-Ersetzen-Semantik für den nicht übereinstimmenden Medientyp zwischen der vorhandenen Adressressource und der in der Anforderung (wie oben beschrieben) wird die Adressressource nun aktualisiert, was sich auf eine nachfolgende GET Anforderung an die Benutzerressource auswirkt Die neue Adresse für den Benutzer wird zurückgegeben.

GET /users/1234 HTTP/1.1
Host: http://www.acmee.com
Accept: application/hal+json; charset=utf-8
Accept-Encoding: gzip, deflate
Accept-Language: en-us
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)
ETag: "e0023aa4e"

{
    "name": "Charlie Gold-Smith",
    "age": 40,
    "job_title": "Senior Software Developer",
    "_links": {
        "self": { "href": "/users/1234" },
        "employee": { "href": "http://www.acmee.com" },
        "curies": [{ "name": "ea", "href": "http://www.acmee.com/docs/rels/{rel}", templated": true}],
        "ea:admin": [
            "href": "/admin/2",
            "title": "Admin"
        ]
    },
    "_embedded": {
        "ea:address": {
            "street": "Standford Ave",
            "zip": "CA 94306",
            "city": "Pablo Alto",
            "country": "United States of America"
            "_links": {
                "self": { "href": "/address/abc" },
                "google_maps": { "href": "http://maps.google.com/?ll=37.4241311,-122.1524475" }
            }
        }
    }
}

Patchen von Teildaten

PATCH ist in RFC5789 definiert und ist nicht direkt Teil der HTTP-Spezifikation. Ein verbreiteter Irrglaube ist, dass das Senden nur der Felder, die teilweise aktualisiert werden sollten, innerhalb einer PATCH Anforderung ausreicht . In der Spezifikation heißt es daher

Die PATCH-Methode fordert, dass ein Satz von Änderungen, die in der Anforderungsentität beschrieben werden, auf die durch den Request-URI identifizierte Ressource angewendet wird. Die Änderungen werden in einem Format dargestellt, das als "Patch-Dokument" bezeichnet wird und durch einen Medientyp identifiziert wird.

Dies bedeutet, dass ein Client die erforderlichen Schritte zur Umwandlung der Ressource von Status A in Status B berechnen und diese Anweisungen an den Server senden muss.

Ein beliebter JSON-basierter Medientyp für das Patchen ist der JSON-Patch .

Wenn sich das Alter und die Berufsbezeichnung unseres Beispielbenutzers ändern und ein zusätzliches Feld, das das Einkommen des Benutzers darstellt, hinzugefügt werden sollte, könnte eine teilweise Aktualisierung mit PATCH mit JSON Patch folgendermaßen aussehen:

PATCH /users/1234 HTTP/1.1
Host: http://www.acmee.com
Content-Type: application/json-patch+json; charset=utf-8
Content-Length: 188
Accept: application/json
If-Match: "e0023aa4e"

[
    { "op": "replace", "path": "/age", "value": 40 },
    { "op": "replace", "path": "/job_title", "value": "Senior Software Developer" },
    { "op": "add", "path": "/salery", "value": 63985.00 }
]

PATCH kann mehrere Ressourcen PATCH aktualisieren und erfordert, dass die Änderungen atomar angewendet werden. PATCH bedeutet, dass entweder alle Änderungen angewendet werden müssen oder keine, was den API-Implementierer mit Transaktionslast belastet.

Ein erfolgreiches Update kann so etwas zurückgeben

HTTP/1.1 200 OK
Location: /users/1234
Content-Type: application/json
ETag: "df00eb258"

{
    "name": "Charlie Smith",
    "age": 40,
    "job_title": "Senior Software Developer",
    "salary": 63985.00
}

ist jedoch nicht nur auf 200 OK Antwortcodes beschränkt.

Um Zwischenaktualisierungen zu verhindern (Änderungen zwischen dem vorherigen Abruf des Repräsentationsstatus und dem Aktualisierungsvorgang), sollten ETag , If-Match oder If-Unmodified-Since Header verwendet werden.

Fehlerbehandlung

Die Spezifikation auf PATCH empfiehlt die folgende Fehlerbehandlung:

Eine Ressource löschen

HTTP-APIs werden häufig verwendet, um eine vorhandene Ressource zu löschen. Dies sollte normalerweise mit DELETE Anforderungen erfolgen.

Wenn der Löschvorgang erfolgreich war, sollte der Server 200 OK . ein entsprechender Fehlercode, falls nicht.

Wenn unser Mitarbeiter Charlie Smith das Unternehmen verlassen hat und wir jetzt seine Datensätze löschen möchten, könnte dies folgendermaßen aussehen:

DELETE /employees/1/charlie-smith HTTP/1.1
Host: example.com

HTTP/1.1 200 OK
Content-Type: application/json

{
    'links': [
        {
            'uri': '/employees',
            'rel': 'create',
            'method': 'POST'
        }
    ]
}

Ressourcen auflisten

Die letzte häufige Verwendung von HTTP-APIs ist das Abrufen einer Liste der vorhandenen Ressourcen auf dem Server. Listen wie diese sollten mithilfe von GET Anforderungen abgerufen werden, da sie nur Daten abrufen .

Der Server sollte 200 OK wenn er die Liste bereitstellen kann, oder einen entsprechenden Fehlercode, falls nicht.

Auflistung unserer Mitarbeiter könnte dann so aussehen:

GET /employees HTTP/1.1
Host: example.com

HTTP/1.1 200 OK
Content-Type: application/json

{
    'employees': [
        {
            'name': 'Charlie Smith',
            'age': 39,
            'job_title': 'Software Developer',
            'salary': 63985.00
            'links': [
                {
                    'uri': '/employees/1/charlie-smith',
                    'rel': 'self',
                    'method': 'GET'
                },
                {
                    'uri': '/employees/1/charlie-smith',
                    'rel': 'delete',
                    'method': 'DELETE'
                },
                {
                    'uri': '/employees/1/charlie-smith',
                    'rel': 'edit',
                    'method': 'PATCH'
                }
            ]
        },
        {
            'name': 'Donna Prima',
            'age': 30,
            'job_title': 'QA Tester',
            'salary': 77095.00
            'links': [
                {
                    'uri': '/employees/2/donna-prima',
                    'rel': 'self',
                    'method': 'GET'
                },
                {
                    'uri': '/employees/2/donna-prima',
                    'rel': 'delete',
                    'method': 'DELETE'
                },
                {
                    'uri': '/employees/2/donna-prima',
                    'rel': 'edit',
                    'method': 'PATCH'
                }
            ]
        }
    ],
    'links': [
        {
            'uri': '/employees/new',
            'rel': 'create',
            'method': 'PUT'
        }
    ]
}