POST

HTTP-menetelmä

HTTP-menetelmän POST määrittely

POST-menetelmä pyytää kohderesurssia käsittelemään pyynnön sisältämän esityksen resurssin oman semantiikan mukaisesti. POST-menetelmää käytetään esimerkiksi (muun muassa) seuraaviin toimintoihin:

  • Tietolohkon, kuten HTML-lomakkeeseen syötettyjen kenttien, toimittaminen tiedonkäsittelyprosessille;
  • Viestin lähettäminen ilmoitustaululle, uutisryhmään, postituslistalle, blogiin tai vastaavaan artikkeliryhmään;
  • Uuden resurssin luominen, jota alkuperäispalvelin ei ole vielä tunnistanut;
  • ja
  • Tietojen lisääminen resurssin olemassa olevaan esitykseen (esityksiin).

Alkuperäpalvelin ilmaisee vastauksen semantiikan valitsemalla sopivan tilakoodin POST-pyynnön käsittelyn tuloksen mukaan; lähes kaikki tässä määrittelyssä määritellyt tilakoodit saatetaan vastaanottaa vastauksena POST-pyyntöön (poikkeuksia ovat 206 (Osittainen sisältö), 304 (Ei muokattu) ja 416 (Alue ei täytettävissä)).

Jos yksi tai useampi resurssi on luotu alkuperäispalvelimella POST-pyynnön onnistuneen käsittelyn tuloksena, alkuperäispalvelimen PITÄÄ lähettää 201 (Created) -vaste, joka sisältää Location-otsikkokentän, joka sisältää ensisijaisen luodun resurssin tunnisteen (kohta 7.1.2) ja esityksen, joka kuvaa pyynnön tilaa ja viittaa samalla uuteen resurssiin (uusiin resursseihin).

POST-pyyntöihin annetut vastaukset ovat välimuistissa vain silloin, kun ne sisältävät nimenomaisen tuoreustiedon (ks. [RFC7234] kohta 4.2.1). POST-välimuistitietoja ei kuitenkaan ole laajalti toteutettu. Tapauksissa, joissa alkuperäispalvelin haluaa asiakkaan voivan tallentaa POST-pyynnön tuloksen välimuistiin siten, että sitä voidaan käyttää uudelleen myöhemmässä GET-pyynnössä, alkuperäispalvelin MAHTAA lähettää 200 (OK) -vastauksen, joka sisältää tuloksen ja Content-Location-otsikkokentän, jolla on sama arvo kuin POST-pyynnön tehokkaalla pyyntö-URI:lla (kohta 3.1.4.2).

Jos POSTin käsittelyn tulos vastaisi olemassa olevan resurssin esitystä, alkuperäispalvelin MAHTAA ohjata käyttäjäagentin kyseiseen resurssiin lähettämällä 303 (Katso muu) -vastauksen, jossa on olemassa olevan resurssin tunniste Location-kentässä. Tästä on se hyöty, että käyttäjäagentti saa resurssin tunnisteen ja että esitys siirretään menetelmällä, joka soveltuu paremmin jaettuun välimuistiin, mutta se aiheuttaa ylimääräisen pyynnön, jos käyttäjäagentti ei ole jo tallentanut esitystä välimuistiin.

IETF (Internet Engineering Task Force) ja W3C (World Wide Web Consortium) ovat määritelleet HTTP-menetelmän POST asiakirjan RFC 7231 kohdassa 4.3.3.

Menetelmän POST kuvaus

keskeneräinen työ

Esimerkki HTTP-menetelmästä POST

Request header:
POST /data HTTP/1.1
Host: api.example.com
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537
Accept: application/json
Accept-Language: de-DE,de;q=0.5
Content-Type: application/json
Content-Length: 100
Connection: keep-alive
Request body:
{
  "key": "value",
  "foo": "bar"
}
Response header:
Content-Type: application/json
Date: Mon, 31 July 2023 14:58:12 GMT
Server: Apache/2.4.7 (Ubuntu)
Cache-Control: no-cache
Location: http://api.example.com/data/123
Response body:
{
  "status": "success",
  "id": 123
}