Headers and tokens and endpoints! Oh My! When I was reading my first few REST API documents the terminology felt overwhelming. Not only that but it seemed each of the different documentations made different assumptions about API experience and changed the language being used. In PowerShell I was adding my authentication token to a hashtable, however, in python I’d add it to a dictionary. Neither document mentioned headers. So, in this article I breakdown the anatomy of a REST API request.
I’ve found the best analogy for understanding REST APIs are letters sent through the mail. The envelope contains supplemental information related to the letter.
Headers
In an API request the headers are a list of information about the request. In the analogy this would be everything at the top of the envelope. A return address shows who the letter was sent from. The stamp authorizes the letter to be process by the mail service. Some postal services stamp the envelope with additional information such as when the letter was mailed.
In the postal system each area on the envelope corresponds to a specific data item. Headers have an equivalent identification system. Instead of using physical location they identify/name themselves with a key. This key then has an associated value. For example, if we had a header called “From” (this would be the key. I would set the value to “Cameron Call”. Another header could be “Return address” and the associated value be “123 Internet Avenue”.
If the request needs to be authorized, I might add a header with the key “Authorization” and the value “$secretK3yfor@uthorization”. This of course would be specified by the API documentation.
These keys and values are called key value pairs and are usually separate by a colon. For example Authorization : $secretK3yfor@uthorization.
Endpoints
The endpoint is the address and who the letter is specifically addressed to. In an example weather API, the address on the envelope would be https://weatherapiexample.com/api/ then the WHO would be “Cities/”. So the endpoint is “https://weatherapiexample.com/api/Cities/”. An api request sent to this endpoint will reply back with a list of cities and weather information about each.
The API may allow us to dig deeper and return more detail information a specific city. Again the address will be https://weatherapiexample.com/api/ but now the who will be /cities/LasVegas/. This makes the endpoint “https://weatherapiexample.com/api/cities/LasVegas/”.
If we ditch the analogy you can think of the endpoint as the URL. If you go to cameroncall.com/blog in a browser you are going to get a list of blogs. If you go to cameroncall.com/projects you are going to get a list of projects.
GET, POST, PUT and PATCH
If I send a box through the mail instead of an envelope it implies that I am sending you an object inside. The request types work in a similar way. If I specify GET as the request method, I’m implying I want to get information. GET is the envelope in the analogy. POST is the box. The API will be expecting information as part of the request and is usually labeled as the “body”. PUT and PATCH in our analogy are also boxes.
FYI some APIs may break from these conventions but they should be the exception not and not the norm.
The Body
The body of a request contains information for the API service to act on. The body is the contents of the envelope or the box in the analogy. If I send a POST request to an API endpoint that handles customer contacts, it will create a new contact using the information in the body. If I sent a GET request it would not have a body at all and we’d really just have sent and empty envelope. But that’s OK! Because our headers had our return address information and just receiving the envelope is enough for it to know to send us a list of contacts.
Parameters
Parameters are last because they completely break the analogy. Much like headers they have a key that identifies them and a value. Parameters are usually used to filter and sort the information returned. They break the analogy because parameters are appended to the end of the endpoint. It would be like addressing a letter to
Cameron Call
123 Internet Ave
Las Vegas, NV 10101
Special Instructions: Write back only using words that begin with “A”
A question mark “?” usually separates the parameter section from the endpoint and an ampersand “&” usually separates different parameters. The tool or language you use to interact with the API will usually add these for you.
