HTTP Verbs/Methods and HTTP Status Codes
We use HTTP protocol to communicate with web servers. It is a communication protocol. It is easy to get confused between HTTP and HTML. The websites we view in our browser are HTML documents. The browser requests a website URL (user initiated) and the server returns a HTML document over HTTP protocol.
It is like you faxing IRS to requesting a copy of your tax filing and they faxing you back your tax return. Here the take form returned is analogous to HTML and the faxing is analogous to ( method of communication) the HTTP protocol.
A HTTP interaction is initiated by the user-agent to a web server. User-agent is typically a web browser. It can also refer to a programs interacting with a web server. The interaction comprises of a request and a response.
The request will at a minimum have the following: Request URL, Request Body and Request Method. The response returned by the server will have a HTTP Status code, and potentially a response body. The response body will have the data if the API returned any. In case of web APIs, the data exchanged can be in a variety of formats. Couple of the popular ones are JSON, and XML(HTML).
A data record can be equated to a row in a table. Let us say there is a Student table with the following columns/ fields: Student ID, Name, DOB(Date of Birth), Gender. Then a row in the table with values: (1, Peter Pan, 1/18/1430, Male) would be considered a record. A partial record would be (1,Male). The interaction with the web service is to create data record(s), read data record(s), update data record(s) and delete data record(s). Hereafter data refers to data records. Since the data is stored in a database, the developer needs to program the API to perform the jobs of creating, reading, updating and deleting data. These are collectively known as CRUD (C=Create, R=Read, U=Update, D=Delete) operations. These CRUD actions map to the different HTTP Request Methods.
| HTTP Request | CRUD | What it typically gets in Request? | What should it do? | What it typically should send in Response? |
|---|---|---|---|---|
| POST | Create | JSON in request body. | Create a record in the database table and potentially redirect to another page. | HTTP status code(201 or 303 if it is a redirect) |
| GET | Read | Resource URL and Optional Query/ URL parameters | Fetch filtered record(s) from database. | Return data as JSON and HTTP status code( 200 for success, 500 for any parsing or server error). You can use 404 Not Found status code if a resource is not found or to hide its existence from an unauthorized client. |
| PUT | Update | JSON in request body. | Updates the entire record. Creates a new one if a macth is not found. | If the target resource does not have a current representation and the PUT successfully creates one, then the origin server MUST inform the user agent by sending a 201 (Created) response. If the target resource does have a current representation and that representation is successfully modified in accordance with the state of the enclosed representation, then the origin server MUST send either a 200 (OK) or a 204 (No Content) response to indicate successful completion of the request.RFC9110 |
| PATCH | Update | JSON in request body. | Partial update of the matching record. | A PATCH request uses a partial of the resource to update portions of the resource. It is a case where you update portions of a record rather than the entire record. For a successful PATCH, common status codes would likely be 200 (OK) or 204 (No Content). If the PATCH method was unsuccessful, status codes such as 304 (Not Modified), 400 (Bad Request), or 422 (Unprocessable Entity) may be seen.RFC9110 |
| DELETE | Delete | Resource URL is what is needed. | Delete the reource defined by the URL | If a DELETE method is successfully applied, the origin server SHOULD send a 202 (Accepted) status code if the action will likely succeed but has not yet been enacted, a 204 (No Content) status code if the action has been enacted and no further information is to be supplied, or a 200 (OK) status code if the action has been enacted and the response message includes a representation describing the status.RFC9110 |
Please refer to RFC9110 for more details.
