HTTP

Most people just see this as what is displayed in a browser, although some browsers do hide this but it stands for Hyper Text Transfer Protocol and if you see an S on the end then that means the communication is encrypted. There is a huge amount that can be said and indeed has been written about HTTP, so there is no value in my repeating that, so I will defer to Mozilla and recommend reading HTTP | MDN.

One area I keep having to try and remember is HTTP Response Codes. When any software sends a request to a server via HTTP the server will respond and include a response code. They are categorised as follows:

  • 1xx (Information) - the code is for information
  • 2xx (Success) - processing was successful but that includes no or partial content
  • 3xx (Redirect) - a different request is required as something hs probably moved
  • 4xx (Client Error) - either the request was invalid, or there was a permissions or location issue
  • 5xx (Server Error) - the request was fine but an error happened within the server

For a complete list and full explanation see HTTP response status codes - HTTP | MDN.

The current, predominant standard is HTTP 1.1, there is also HTTP/2, which is designed to reduce latency by changing how the data is packaged and transported, it does not change the status codes, header fields and so on. Then there is also HTTP/3, which is more different, in that it is based on QUIC, unlike the previous versions which are based on TCP. It is also worth noting that all of these can, and do, co-exist within a browser and various support libraries.

Programmatic Communication

A lot of HTTP traffic is browser based, however there is a lot of HTTP traffic that does not have a browser at one end and this is where we have more control over what happens but also less in the way of standards, or rather there are several. I have also seen organisations adopt non-standard approaches as their standard for their own reasons.

REST

REpresentational State Transfer, also known as REST, is a common standard, but it is not actually a defined standard, it is in fact an architectural style, or way of working. Whilst REST is a common "style" it does not lay down the rules on everything. When an API is implemented using a REST style, then it is usually said to be RESTful. This section is my view based on what I have seen, done and learnt, however there is nothing to say it is right. Given that REST is an architectural style then there is also nothing to say I am wrong....

See What is REST, or possibly The RESTful cookbook

Methods or Verbs

It is very important to agree on what HTTP methods (HTTP request methods - HTTP | MDN) to implement and also what HTTP response codes (HTTP response status codes - HTTP | MDN) each of these is going to possibly return. This is what I would suggest.

  • GET - self explanatory, it gets things, but without changing state, typically returning a 200 (Success) or 404 (Not Found)
  • POST - create new item/resource should return 201 (Created), should return status information and a Location header
  • PUT - this should primarily update existing resources, should return 201 (Created) if it made something new, although it could refuse to do this, generally returns a 200 (Success)
  • DELETE - delete the specified item, should return 200 (OK) if done, or 202 (Accepted) if the request is in a queue
  • PATCH - not often implemented, but should only update what is specified
  • OPTIONS - this should list what verbs are supported, but is not often implemented

PUT and DELETE are "idempotent", meaning that multiple identical requests have the same effect as any one of those requests.

REST can work with XML, JSON, YAML or anything else, it is not limited to one format of data and indeed can support many types.