HTTP Methods

The HTTP specification defines several different kinds of requests—or methods—that clients can send to services. These methods include GET, POST, DELETE, and PATCH. These methods roughly correspond to the four basic operations you use to interact with records in a database: create, read, update, or delete. This collection of operations is sometimes abbreviated as CRUD.

Each method has its own semantic meaning. A web service will generally behave differently depending on a request's method, even for the same URL. For example, a GET request for /user/7 is very different from a DELETE request for /user/7.

GET

When the client only wants to read data from a service, it sends a GET request, which has this form:

GET /some-endpoint/23 HTTP/1.1
Host: example.com
Accept: */*

The web service will parse the URL and send back the requested data in its response. The requested resource is generally not modified by a GET request.

Some methods allow extra parameters to be passed in the request body. GET requests do not have a body. The parameters must be sent in the URL or through custom headers. In this example, 23 is sent as a parameter.

When embedding parameters directly in the URL, the client must escape characters that have special meaning, such as / and #. These characters are escaped using percent-encoding. For example, when passing the parameter Either/Or to the endpoint /album, the URL would be /album/Either%2FOr. The forward slash character has ASCII value 47, which in hexadecimal is 2F. The service is responsible for decoding parameters before using them. If you are using Express, then the parameters are automatically decoded.

POST

When the client wants the web service to create new data, it sends a POST request. A request for sending a new chat message between two users might look like this:

POST /send HTTP/1.1
Host: example.com
Accept: */*
Content-Type: application/json
Content-Length: 60

{"from.user": 4534, "to.user": 849954, "message": "i wuv u"}

The client often must include parameters to the request. When the parameters are short and few, they can be included in the URL itself or in custom headers. Longer parameters should be placed in the body of the request as its payload. Here the payload is formatted in JSON.

A service commonly responds to a POST request by sending in its response the ID of the new record it created.

DELETE

When the client wants the web service to delete data, it sends a DELETE request, which has this form:

DELETE /message/1563 HTTP/1.1
Host: example.com
Accept: */*

As with POST, parameters can appear in the URL, in the body, or in custom headers.

PATCH

When the client wants to update existing data, it sends a PATCH request, which has this form:

PATCH /user/119/settings HTTP/1.1
Host: example.com
Accept: */*
Content-Type: application/json
Content-Length: 33

{"theme": "dark", "tab.width": 2}

The ID of the record to update is usually passed as a parameter. Only the modified fields of the data are included in the request.

As with POST and DELETE, parameters can appear in the URL, in the body, or in custom headers.