HTTP
HTTP voor API's

Android Angular 2 AngularJS C# Language HTML Java Language JavaScript Node.js PHP Python Language
Zoeken…


Opmerkingen

HTTP API's gebruiken een breed spectrum van HTTP-werkwoorden en geven meestal JSON- of XML-antwoorden terug.

Maak een bron aan

Niet iedereen is het eens over wat de meest semantisch correcte methode voor het maken van bronnen is. Uw API kan dus POST of PUT aanvragen accepteren, of een van beide.

De server moet reageren met 201 Created als de bron met succes is gemaakt. Kies de meest geschikte foutcode als dit niet het geval was.

Als u bijvoorbeeld een API opgeeft om werknemersrecords te maken, kan het verzoek / antwoord er als volgt uitzien: 

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"
        }
    ]
}

Met inbegrip van de links JSON velden in de reactie kan de klant toegang tot bronnen die verband houden met de nieuwe bron en de toepassing in zijn geheel, zonder dat ze hun URI's of methoden voren weten.

Bewerk een bron

Een bron bewerken of bijwerken is een veelgebruikt doel voor API's. U kunt bewerkingen uitvoeren door POST , PUT of PATCH aanvragen naar de betreffende bron te verzenden. Hoewel POST gegevens mag toevoegen aan de bestaande weergave van een bron , wordt het aanbevolen PUT of PATCH omdat deze een meer expliciete semantiek overbrengen.

Uw server moet reageren met 200 OK als de update is uitgevoerd, of 202 Accepted als deze nog moet worden toegepast. Kies de meest geschikte foutcode als deze niet kan worden voltooid.

Volledige updates

PUT heeft de semantiek van het vervangen van de huidige representatie door de payload die in het verzoek is opgenomen. Als de payload niet van hetzelfde type weergave is als de huidige weergave van de bron die moet worden bijgewerkt, kan de server beslissen welke aanpak moet worden gevolgd. RFC7231 definieert dat de server dat ook kan

  • Configureer de doelbron opnieuw om het nieuwe mediatype weer te geven
  • Transformeer de PUT-weergave naar een indeling die consistent is met die van de bron voordat u deze opslaat als de nieuwe bronstatus
  • Weigeren het verzoek met een 415 Unsupported Media Type antwoord dat aangeeft dat de doelbron beperkt is tot een specifieke (set) mediatypen.

Een basisresource met een JSON HAL- weergave zoals ... 

{
    "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"
        ]
    }
}

... ontvangt mogelijk een updateverzoek als dit 

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"
}

De server kan nu de status van de resource vervangen door de gegeven body van het verzoek en ook het content-type wijzigen van application/hal+json naar application/json of de JSON-payload omzetten in een JSON HAL-weergave en vervolgens de inhoud van de resource vervangen met de getransformeerde of weiger het updateverzoek vanwege een niet-toepasbaar mediatype met een reactie van 415 Unsupported Media Type .

Er is een verschil tussen het direct vervangen van de inhoud of het eerst transformeren van de weergave naar het gedefinieerde representatiemodel en vervolgens het vervangen van de bestaande inhoud door de getransformeerde. Een volgend GET verzoek retourneert het volgende antwoord op een directe vervanging: 

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"
}

terwijl de transformatie en vervolgens de benadering vervangen de volgende weergave zal opleveren: 

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"
        ]
    }
}

Bijwerkingen

Merk op dat PUT bijwerkingen mag hebben, hoewel het is gedefinieerd als idempotent operatie! Dit is gedocumenteerd in RFC7231 als

Een PUT-verzoek dat op de doelbron wordt toegepast, kan bijwerkingen op andere middelen hebben . Een artikel kan bijvoorbeeld een URI hebben voor het identificeren van "de huidige versie" (een bron) die los staat van de URI's die elke specifieke versie identificeren (verschillende bronnen die op een gegeven moment dezelfde status deelden als de huidige versiebron). Een succesvol PUT-verzoek voor "de huidige versie" URI kan daarom een nieuwe versiemiddel creëren naast het wijzigen van de status van het doelmiddel, en kan ook leiden tot koppelingen tussen de gerelateerde middelen.

Het produceren van extra logboekvermeldingen wordt meestal niet als bijwerking beschouwd, omdat dit in het algemeen geen toestand van een bron is.

Gedeeltelijke updates

RFC7231 vermeldt dit met betrekking tot gedeeltelijke updates:

Gedeeltelijke inhoudsupdates zijn mogelijk door een afzonderlijk geïdentificeerde resource te targeten met een status die een deel van de grotere resource overlapt, of door een andere methode te gebruiken die specifiek is gedefinieerd voor gedeeltelijke updates (bijvoorbeeld de PATCH-methode die is gedefinieerd in RFC5789 ).

Gedeeltelijke updates kunnen daarom in twee smaken worden uitgevoerd:

Gedeeltelijke update met overlappende status

Als een gebruikersvertegenwoordiging gedeeltelijk moet worden bijgewerkt vanwege een verplaatsing van een gebruiker naar een andere locatie, in plaats van de gebruiker rechtstreeks bij te werken, moet de gerelateerde bron direct worden bijgewerkt, wat een gedeeltelijke update van de gebruikersvertegenwoordiging weerspiegelt.

Voor de verhuizing had een gebruiker de volgende weergave 

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" }
            }
        }
    }
}

Terwijl de gebruiker naar een nieuwe locatie verhuist, werkt ze haar locatie-informatie als volgt bij: 

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"
}

Met de transformatie-voor-vervang semantiek voor het niet-overeenkomende mediatype tussen de bestaande adresresource en die in de aanvraag, zoals hierboven beschreven, wordt de adresresource nu bijgewerkt, wat het effect heeft dat op een volgende GET aanvraag op de gebruikersresource het nieuwe adres voor de gebruiker wordt geretourneerd. 

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" }
            }
        }
    }
}

Gedeeltelijke gegevens patchen

PATCH is gedefinieerd in RFC5789 en maakt op zichzelf geen direct deel uit van de HTTP-specificatie. Een veel voorkomend misverstand is dat het verzenden van alleen de velden die gedeeltelijk moeten worden bijgewerkt voldoende is binnen een PATCH verzoek. In de specificatie staat daarom

De PATCH-methode vraagt dat een reeks wijzigingen die zijn beschreven in de verzoekentiteit worden toegepast op de resource die is geïdentificeerd door de Request-URI. De set wijzigingen wordt weergegeven in een indeling die een 'patch-document' wordt genoemd, geïdentificeerd door een mediatype.

Dit betekent dat een client de benodigde stappen moet berekenen die nodig zijn om de resource van status A naar status B te transformeren en deze instructies naar de server te verzenden.

Een populair op JSON gebaseerd mediatype voor patching is JSON Patch .

Als de leeftijd en de functie van onze voorbeeldgebruiker veranderen en een extra veld met de inkomsten van de gebruiker moet worden toegevoegd, kan een gedeeltelijke update met behulp van PATCH met behulp van JSON Patch er als volgt uitzien: 

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 kan meerdere bronnen tegelijk bijwerken en vereist dat de wijzigingen atomair worden toegepast, wat betekent dat alle wijzigingen moeten worden aangebracht of helemaal geen, wat de API-implementator transactiedruk oplevert.

Een succesvolle update kan zoiets retourneren 

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
}

is echter niet beperkt tot 200 OK antwoordcodes.

Om tussentijdse updates te voorkomen (wijzigingen aangebracht tussen de vorige ophaalactie van de representatiestatus en de update) moet de header ETag , If-Match of If-Unmodified-Since worden gebruikt.

Foutafhandeling

De specificatie op PATCH beveelt de volgende foutafhandeling aan:

Type Foutcode
Misvormd patch-document 400 Bad Request
Niet-ondersteund patch-document 415 Unsupported Media Type
Onverwerkbaar verzoek, dwz als de oplossing ongeldig zou worden door de patch toe te passen 422 Unprocessable Entity
Bron niet gevonden 404 Not Found
Conflicterende status, dwz een hernoeming (verplaatsing) van een veld dat niet bestaat 409 Conflict
Conflicterende wijziging, dwz als de client een If-Match of If-Unmodified-Since header gebruikt waarvan de validatie is mislukt. Als er geen voorwaarde beschikbaar was, moet de laatste foutcode worden geretourneerd 412 Precondition Failed of 409 Conflict
Gelijktijdige wijziging, dwz als het verzoek moet worden toegepast voordat verdere PATCH aanvragen worden geaccepteerd 409 Conflict

Verwijder een bron

Een ander veelgebruikt gebruik van HTTP API's is het verwijderen van een bestaande bron. Dit moet meestal worden gedaan met DELETE aanvragen.

Als het verwijderen is gelukt, moet de server 200 OK retourneren; een geschikte foutcode als dit niet het geval was.

Als onze medewerker Charlie Smith het bedrijf heeft verlaten en we nu zijn gegevens willen verwijderen, kan dat er zo uitzien: 

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'
        }
    ]
}

Lijst bronnen

Het laatste veelgebruikte gebruik van HTTP API's is het verkrijgen van een lijst met bestaande bronnen op de server. Lijsten zoals deze moeten worden verkregen met behulp van GET aanvragen, omdat deze alleen gegevens ophalen .

De server moet 200 OK retourneren als hij de lijst kan leveren, of een geschikte foutcode als dat niet het geval is.

Het opsommen van onze medewerkers kan er dan als volgt uitzien: 

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'
        }
    ]
}


Modified text is an extract of the original Stack Overflow Documentation
Licentie onder CC BY-SA 3.0
Niet aangesloten bij Stack Overflow