The request that a user sends in,

can provide a lot more information than just the end points and HTTP can.

Different aspects of the request can be used to change the format of the response.

The version of the API and more.

Let's open PostMan and take a look at an actual request.

You can close the launch screen for now,

as we're going to be making a very simple request.

In the address bar, much like a web browser, we can enter an endpoint url.

We'll use the treehouse url plus add the user name to get profile data.

This will return an HTML page as a user profile.

We can preview just like browser.

If we add .json to the end We get our profile data as JSON results.

We can choose the Pretty format for the JSON data

We can send more information to the API through parameters.

By adding topic as the key and security as the value,

we can see these properties are added to the URL.

This is known as a query or query string.

When we send this request, we will now see only badges related to the security topic.

Everything after the question mark is treated as a set of key and value pairs.

For example, this query string gives us two keys.

Order and sort, and two values, desk for descending and points.

Likely, this would cause us to send back a collection of games

sorted by their points in descending order.

There's nothing stopping you from doing all of your extra work

in the query stream.

And many APIs handle their requests in this way, but

it's not always the best approach.

For instance, what if you wanted to let users request a record as either

xml or json?

In our tree house example users can request the format

by adding the .json to the end of the url.

We could also send this information using the HTTP headers.

If the API accepts the format in a header, you could send something like this,

Accept as the key and application/json as the value.

And once again we see the JSON results.

HTTP headers are one of the more amazing and useful pieces to a great API.

The HTTP spec provides a very thorough list of headers that can and

should be accepted by an API.

You don't have to accept all of them, of course, but

let's look at a few that you should probably always pay attention to.

Accept, like we'd showed earlier,

specifies the file format the requester wants.

Accept-Language specifies the human-readable language, like English,

Spanish, or Russian.

Cache-Control is one you might wanna be picky with, but

it specifies whether the response can be generated from a cache or

a quick-to-access memory bank of data or not.

Again, you don't have to implement all of the headers.

You don't have to implement any of them.

But smarter clients and smarter APIs take advantage of of the http spec,

to make transactions cleaner and more explicit.

When consuming a third party API make sure you check the documentation to understand

which headers that API accepts.

You might be thinking that your user will send all of their request's

content to you in the query string.

Most git endpoints accept parameters through the quarry screen

where they are URL encoded.

Post requests on the other hand encode the content as either xwww form URLencoded,

or form data and typically send it through as the body of the request.

This hides the data from the URL but still makes it available to the API.

You can use Postman to test sending query parameters, headers,

and body data to any API you´re using.

Before we finish up with the request, I wanna point out one more thing that we´ve

been requesting in our game example, but you might have not have noticed.

Did you notice the v1 in all of the URLs so far?

That's specifies the version of the API that we're hitting.

We want to always provide version numbers for our APIs.

And we want to make sure that the Legacy APIs exist for as long as possible.

When your app comes out with a brand new amazing version, and

you need a new API for it, bump the version number up and

keep the old API around as long as you can.

We all want users to use the latest and greatest.

But upgrading a mobile app, or a shell script, that only gets used a few

times a year, might not be something our API's users can do right away.

The longer our API version sticks around less the web breaks.

When consuming a third party API, make sure you reference documentation for

the particular version you are using as versions can vary greatly.

Also it's always a good idea to upgrade to the latest API versions when possible.

Not only to get the latest and greatest features, but

also to make sure that your application continues to work as expected.

All right, that's half the request response cycle.

Let's look at the other half and

how an API can provide more information to its users than just a blob of JSON or XML.