HTTP verbs and status codes

The verb says what to do

A request carries a verb that says what to do. A response carries a number that says how it went. Learn the four verbs and the five number families, and most web traffic becomes readable.

A verb, and what it asks

Four verbs cover most of what you will see. Get retrieves a representation of the resource. Post asks the resource to process the data enclosed in the request, according to its own rules; creating something is one common use. Put asks that the resource be created or replaced with the state in the request. And delete asks the server to remove the resource's association with its current functionality.

• GET · Retrieve a representation · search · navy
• POST · Process the enclosed data · pencil · navy
• PUT · Create or replace the resource · file · amber
• DELETE · Remove the resource · cross · slate

Status codes come in families

A status code is three digits, and the first digit gives the family. One hundred series: informational. Two hundred series: successful. Three hundred series: redirection. Four hundred series: client error, meaning the request contains bad syntax or cannot be fulfilled. And five hundred series: server error, meaning the server failed to fulfil an apparently valid request.

• 5xx Server error · The server failed. · warning
• 4xx Client error · Bad or unfulfillable request. · cross
• 3xx Redirection · Further action needed. · share
• 2xx Successful · Received and accepted. · check
• 1xx Informational · Received; continuing. · text

A record that is not there

Now ask for a record that is not there. Same verb, a different path: Patient slash nine nine nine. The server replies four hundred and four, Not Found. The standard says this means the server did not find a current representation for the resource, or is not willing to say that one exists. The first digit, four, tells you the request could not be fulfilled.

• GET /Patient/999 HTTP/1.1
• Host: localhost
• Accept: application/json

A code, and what it says

Here are the codes you will meet most. Two hundred, O K: the request succeeded. Two zero one, Created: it resulted in a new resource. Four hundred, Bad Request: the request has bad syntax. Four zero one, Unauthorized: the request lacks valid authentication credentials. Four zero four, Not Found. And five hundred, Internal Server Error: the server hit something unexpected.

• 200 OK · The request succeeded · check · navy
• 201 Created · A new resource was created · star · navy
• 400 Bad Request · The request is badly formed · warning · amber
• 401 Unauthorized · No valid credentials · lock · amber
• 404 Not Found · No current resource there · search · slate
• 500 Server Error · The server failed · gear · slate

FHIR's actions are these verbs

FHIR uses these same verbs. Reading a resource is a get. Creating a new resource, with a server assigned id, is a post. Updating a resource by its id is a put. And deleting is a delete. The FHIR page also says its API follows the standard's rules for particular status codes, so a four zero four from a FHIR server means just what you learned here.

• read a resource · GET [base]/[type]/[id] · search · navy
• create a resource · POST [base]/[type] · star · navy
• update a resource · PUT [base]/[type]/[id] · pencil · amber
• delete a resource · DELETE [base]/[type]/[id] · cross · slate

Check yourself

Pause and think. A server replies with a four zero four status. In which family is it? The answer: four hundred series, client error.

• 4xx, client error: the request could not be fulfilled
• 2xx, successful
• 5xx, server error
• 3xx, redirection

Keep these in mind

Get reads, post processes, put creates or replaces, and delete removes. The first digit of a status code is its family. Two hundred series worked, four hundred series means the request failed, and five hundred series means the server failed. And FHIR reuses these verbs and codes.

• GET reads, POST processes, PUT creates or replaces, DELETE removes
• The first digit of a status code is its family
• 2xx worked; 4xx the request failed; 5xx the server failed
• FHIR reuses these verbs and codes