Basic Parts of an API Request

Written by

Basic Parts of an API Request

Sometimes understanding URLs and requests can be intimidating. If you’re wanting to get into API programming (e.g. REST, SOAP, web [which isn’t considered part of the family, but follows the same procedures]) it helps to understand basic components of an API request.

The two major parts developers care about are:

  • Request URL
  • Reqeust Body

I’ll be using a post office analogy. Because post offices are great ancient American relics (yes, that was sarcasm). The equivalences for these for the post office analogy are:

Request URL Shipping Address
Request Body Letter

Obviously, there are nuances with each service, but those are the 2 major components. Now, lets’ dive into each component.

Request URL: Telling the Postman Where and How to Send It

If you’re used the web at all, you’re used to a web address:

http://somethingerrather.com/here/i/am/

http is the protocol. It’s basically like putting your letter in the mailbox. The post office understands that anything in the mailbox should be collected. If you try to deliver all the mail to the cashier at your local convenience store, they wouldn’t know what to do with it (and your identity would probably be stolen).

REST APIs typically use standard http protocol.

But how does your web browser know where to get the content? In an attempt to not complicate the answer, your browser sends the URL to a cental server (like a post office) that routes the domain (the sometherrather.com part) to the server registered for the domain.

Sometimes a protocol may have a port number associated with it:

http://someserver.com:2020

2020 is the port number. This is not typical for public APIs and is usually used for internal devleopment.

The registered server takes care of the /here/i/am part (commonly referred to as the “path”) that services are most iterested in. So from here on out we’ll ignore the domain.

tl;dr: The request URL tells the API client the “where” of the request.

Paths

Paths are handled by the server that hosts the API.

In the post office example, this is like the administrator of a business that recieves the letter.

As a standard, a path is preceded by a slash (‘/‘).

Paramters

Remember when I showed you the URL above?

http://somethingerrather.com/here/i/am/

There’s another part that’s sometimes used: the query parameters. Query parameters are key and value pairs that provide details to whatever service consumes the path.

It’s denoted starting with question mark (‘?’):

http://somethingerrather.com/here/i/am/name=frank&greeting=hello&repeat=3

The part after the ‘?’ is the query: ?name=frank&greeting=hello&repeat=3. Hard to read? You betcha! Even developers like to use libraries that split the query into something easy to comprehent. Simply put, this is the query:

key value
name frank
greeting hello
repeat 3

Now the API service knows what to do!

For the post office analogy this is like providing additional shipping information like adding an ATTN: to the address or a [FRAGILE: HANDLE WITH CARE] sticker to the side.

tl;dr: Paramters tell how to deliver something.

The Body: The Letter Within the Parcel

While getting envelopes around the holidays is always exciting (I’m always up for getting $10 bills) it can always be disappointing if you open up an envelope and see nothing.

Yes, the envelope can tell you a lot. An envelope from your utility company that says PAST DUE can indicate something should be done pretty soon.

So it’s pretty common for a REST API to contain a body as well. REST bodies are usually in JSON format, since JSON allows for free-flow strucutre and is easily parseable.

However, JSON is not required. You can send virtually anything from numbers to complex graphs, and even your kitchen sink (that last one’s not recommended)!

Here’s one example:

REQUEST:
    POST https://example.com/resource/add

BODY:
    {
        "name": "Jane Doe",
        "gender": "f",
        "account": 1234
    }

Sideline: Request Methods

Notice the “POST” request method. There are other HTTP methods as well and are equivalent to the type of delivery within the postal service.

For example, once upon a time in America, whenever someone would want to subscribe to a magazine (another ancient relic, but bear with me), they would need to send in a registration form. We can call this a “PUT” request. Each month the magazine comes out, the reader goes out to the mailbox and gets his magazine. This can be considered a “GET” request. Same transport, but a different method of sending an retrieving mail.

Back to the Body

The body is typically only implemented in POST-like request methods. While HTTP (as far as I know) doesn’t forbid a body with ‘GET’ requests it’s bad table manners to include a body, so a lot of libraries strip the body if a client tries to do a ‘GET’ request with a body.

lt;dr: The body is the thing you want delivered.

Conclusion

In this post I (hopefully) provided a brief overview of how APIs work. Before you run off to grab more coffee, here’s an overview comparison of APIs vs. the post office analogy.

Post Office Example API Example
URL container for the mail Mailbox Protocol `http`
method of delivery Sending, pickup, … HTTP Method GET, POST, PUT, PATCH, DELETE, …
Where to send the mail 1234 N Example St., … domain `www.example.com`
Where to go after delivery ATTN: Person at company Path `/resource/get/1`
How to handle the delivery FRAGILE: HANDLE WITH CARE! Query Paramters `name=henry&number=1234`
Body Contents of the letter Dear Sir, In my opinion … Body `{“name”: “Henry”, “number”: 1234, …}`

Did you like this article?

Did you know I'm available for hire?

Send me an email here: hireme@jordanhewitt.pro

Or connect with me in Wire: @nswered