HTTP
HTTP för API: er

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


Anmärkningar

HTTP-API: er använder ett brett spektrum av HTTP-verb och returnerar vanligtvis JSON- eller XML-svar.

Skapa en resurs

Inte alla är överens om vad den mest semantiskt korrekta metoden för resursskapning är. Således kan ditt API acceptera POST eller PUT förfrågningar, eller antingen.

Servern ska svara med 201 Created om resursen har skapats. Välj den mest lämpliga felkoden om den inte var det.

Om du till exempel tillhandahåller ett API för att skapa medarbetarposter kan begäran / svaret se ut så här: 

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

Inklusive links JSON-fält i svaret gör det möjligt för klienten att få åtkomst till resursen relaterad till den nya resursen och till applikationen som helhet, utan att behöva känna till sina URI: er eller metoder i förväg.

Redigera en resurs

Att redigera eller uppdatera en resurs är ett vanligt syfte för API: er. Redigeringar kan uppnås genom att skicka antingen POST , PUT eller PATCH förfrågningar till respektive resurs. Även om POST tillåts att lägga till data till en resurs befintliga representation rekommenderas det att använda antingen PUT eller PATCH eftersom de förmedlar ett mer tydligt semantiskt.

Din server ska svara med 200 OK om uppdateringen utfördes, eller 202 Accepted om den ännu inte har tillämpats. Välj den mest lämpliga felkoden om den inte kan slutföras.

Fullständiga uppdateringar

PUT har semantiken att ersätta den nuvarande representationen med nyttolasten som ingår i begäran. Om nyttolasten inte är av samma representationstyp som den aktuella representationen av resursen som ska uppdateras, kan servern bestämma vilken strategi som ska tas. RFC7231 definierar att servern kan antingen

  • Konfigurera målresursen så att den speglar den nya medietypen
  • Omvandla PUT-representationen till ett format som överensstämmer med resouche-formatet innan du sparar den som det nya resurstillståndet
  • Avvisa begäran med ett svar på 415 Unsupported Media Type indikerar att målresursen är begränsad till en specifik (uppsättning) mediatyper.

En basresurs som innehåller en JSON HAL- representation som ... 

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

... kan få en uppdateringsbegäran som denna 

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

Servern kan nu ersätta tillståndet för resursen med det angivna förfrågningsorganet och också ändra innehållstypen från application/hal+json till application/json eller konvertera JSON nyttolast till en JSON HAL-representation och sedan ersätta innehållet i resursen med den transformerade eller avvisa uppdateringsbegäran på grund av en otillåten mediatyp med ett svar på 415 Unsupported Media Type ostödat medietyp.

Det finns en skillnad mellan att ersätta innehållet direkt eller först transformera representationen till den definierade representationsmodellen och sedan ersätta det befintliga innehållet med det transformerade. En efterföljande GET begäran returnerar följande svar på en direkt ersättning: 

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

medan omvandlingen och sedan ersätta tillvägagångssättet returnerar följande representation: 

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

Bieffekter

Observera att PUT tillåts ha biverkningar även om det definieras som idempotent operation! Detta dokumenteras i RFC7231 som

En PUT-begäran som tillämpas på målresursen kan ha biverkningar på andra resurser . Till exempel kan en artikel ha en URI för att identifiera "den aktuella versionen" (en resurs) som är åtskild från URI: erna som identifierar varje viss version (olika resurser som vid ett tillfälle delade samma tillstånd som den aktuella versionens resurs). En framgångsrik PUT-förfrågan på URI för "den aktuella versionen" kan därför skapa en ny version av resursen utöver att ändra målresursens tillstånd och kan också leda till att länkar läggs till mellan relaterade resurser.

Att producera ytterligare loggposter anses vanligtvis inte som bieffekt eftersom det verkligen inte är något resursläge i allmänhet.

Delvisa uppdateringar

RFC7231 nämner detta angående delvisa uppdateringar:

Partiella innehållsuppdateringar är möjliga genom att rikta in sig på en separat identifierad resurs med tillstånd som överlappar en del av den större resursen, eller genom att använda en annan metod som har definierats specifikt för partiella uppdateringar (till exempel PATCH-metoden definierad i RFC5789 ).

Delvisa uppdateringar kan därför utföras i två smaker:

Delvis uppdatering med överlappande tillstånd

Om en användarrepresentation behöver delvis uppdateras på grund av att en användare flyttas till en annan plats, i stället för att uppdatera användaren direkt, bör den relaterade resursen uppdateras direkt vilket återspeglar en delvis uppdatering av användarrepresentationen.

Före flytten hade en användare följande representation 

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

När användaren flyttar till en ny plats uppdaterar hon sin platsinformation så här: 

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

Med den semantiska transformationen före ersättningen för den inte anpassade medietypen mellan den befintliga adressresursen och den i begäran, som beskrivits ovan, uppdateras nu adressresursen vilket har effekten att på en efterföljande GET begäran på användarresursen den nya adressen för användaren returneras. 

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

Lappning av partiella data

PATCH definieras i RFC5789 och är inte direkt en del av HTTP-specifikationen i sig. En vanlig missuppfattning är att det bara räcker med att skicka fälten som bör uppdateras delvis inom en PATCH begäran. Specifikationen anger därför

PATCH-metoden begär att en uppsättning ändringar som beskrivs i begäringsenheten tillämpas på den resurs som identifieras av Request-URI. Uppsättningen av förändringar representeras i ett format som kallas ett "patchdokument" som identifieras av en medietyp.

Detta innebär att en klient ska beräkna de nödvändiga stegen som krävs för att omvandla resursen från tillstånd A till tillstånd B och skicka dessa instruktioner till servern.

En populär JSON-baserad mediatyp för lapp är JSON Patch .

Om åldern och jobbtiteln för vår exempelanvändare ändras och ett ytterligare fält som representerar användarens inkomster bör läggas till kan en partiell uppdatering med PATCH med JSON Patch se ut så här: 

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 uppdatera flera resurser på en gång och kräver att tillämpa ändringarna atomiskt vilket innebär att antingen alla ändringar måste tillämpas eller inte alls som lägger transaktionella bördor för API-implementatorn.

En framgångsrik uppdatering kan returnera något liknande 

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
}

men är inte begränsat till bara 200 OK svarskoder.

För att förhindra mellanuppdateringar (ändringar som gjorts mellan tidigare hämtning av representationsläget och uppdateringen) ETag , If-Match eller If-Unmodified-Since rubrik bör användas.

Felhantering

Specifikationen på PATCH rekommenderar följande felhantering:

Typ Felkod
Felformat patchdokument 400 Bad Request
Ostödda patchdokument 415 Unsupported Media Type
Obehandlingsbar begäran, dvs om resursmottagaren skulle bli ogiltig genom att applicera lappen 422 Unprocessable Entity
Resursen hittades inte 404 Not Found
Konfliktillstånd, dvs. ett nytt namn (flytt) av ett fält som inte finns 409 Conflict
Konfliktändring, dvs om klienten använder en If-Match eller If-Unmodified-Since rubrik vilken validering misslyckades. Om ingen förutsättning fanns tillgänglig, ska den senare felkoden returneras 412 Precondition Failed eller 409 Conflict
Samtidig modifiering, dvs om begäran måste tillämpas innan acceptera ytterligare PATCH begäranden 409 Conflict

Radera en resurs

En annan vanlig användning av HTTP-API: er är att ta bort en befintlig resurs. Detta bör vanligtvis göras med DELETE förfrågningar.

Om borttagningen var framgångsrik bör servern returnera 200 OK ; en lämplig felkod om den inte var det.

Om vår anställd Charlie Smith har lämnat företaget och vi nu vill ta bort hans poster kan det se ut så här: 

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

Lista resurser

Den senaste vanliga användningen av HTTP API: er är att få en lista över befintliga resurser på servern. Listor som detta bör fås med GET förfrågningar, eftersom de bara hämtar data.

Servern ska returnera 200 OK om den kan leverera listan, eller en lämplig felkod om inte.

Att lista våra anställda kan då se ut så här: 

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
Licensierat under CC BY-SA 3.0
Inte anslutet till Stack Overflow