Heads up! To view this whole video, sign in with your Courses account or enroll in your free 7-day trial. Sign In Enroll
Preview
Start a free Courses trial
to watch this video
With our endpoint nouns and HTTP method verbs, we can start to build up the design of our API, but what happens when we need more information than those two things can give us?
Query strings come after a question mark (?) in a URL. They have keys and values.
Here is a complete list of HTTP header fields that are available on requests. For many clients and servers, you can also create your own, usually following a format like X-MY-SPECIAL-HEADER.
The request that a user sends in,
0:00
can provide a lot more information
than just the end points and HTTP can.
0:02
Different aspects of the request can be
used to change the format of the response.
0:08
The version of the API and more.
0:12
Let's open PostMan and
take a look at an actual request.
0:14
You can close the launch screen for now,
0:20
as we're going to be making
a very simple request.
0:22
In the address bar, much like a web
browser, we can enter an endpoint url.
0:25
We'll use the treehouse url plus add
the user name to get profile data.
0:31
This will return an HTML
page as a user profile.
0:40
We can preview just like browser.
0:44
If we add .json to the end We get
our profile data as JSON results.
0:48
We can choose the Pretty format for
the JSON data
0:56
We can send more information
to the API through parameters.
1:03
By adding topic as the key and
security as the value,
1:09
we can see these properties
are added to the URL.
1:15
This is known as a query or query string.
1:19
When we send this request, we will now see
only badges related to the security topic.
1:23
Everything after the question mark is
treated as a set of key and value pairs.
1:32
For example,
this query string gives us two keys.
1:37
Order and sort, and two values,
desk for descending and points.
1:41
Likely, this would cause us to
send back a collection of games
1:47
sorted by their points
in descending order.
1:50
There's nothing stopping you from
doing all of your extra work
1:54
in the query stream.
1:57
And many APIs handle their
requests in this way, but
1:59
it's not always the best approach.
2:02
For instance, what if you wanted to
let users request a record as either
2:04
xml or json?
2:09
In our tree house example
users can request the format
2:11
by adding the .json to the end of the url.
2:14
We could also send this information
using the HTTP headers.
2:18
If the API accepts the format in a header,
you could send something like this,
2:25
Accept as the key and
application/json as the value.
2:32
And once again we see the JSON results.
2:41
HTTP headers are one of the more amazing
and useful pieces to a great API.
2:44
The HTTP spec provides a very
thorough list of headers that can and
2:51
should be accepted by an API.
2:56
You don't have to accept all of them,
of course, but
2:58
let's look at a few that you should
probably always pay attention to.
3:01
Accept, like we'd showed earlier,
3:06
specifies the file format
the requester wants.
3:08
Accept-Language specifies
the human-readable language, like English,
3:11
Spanish, or Russian.
3:16
Cache-Control is one you might
wanna be picky with, but
3:17
it specifies whether the response
can be generated from a cache or
3:21
a quick-to-access memory bank of data or
not.
3:25
Again, you don't have to
implement all of the headers.
3:29
You don't have to implement any of them.
3:32
But smarter clients and smarter APIs
take advantage of of the http spec,
3:34
to make transactions cleaner and
more explicit.
3:39
When consuming a third party API make sure
you check the documentation to understand
3:43
which headers that API accepts.
3:48
You might be thinking that your user
will send all of their request's
3:51
content to you in the query string.
3:54
Most git endpoints accept parameters
through the quarry screen
3:56
where they are URL encoded.
4:00
Post requests on the other hand encode the
content as either xwww form URLencoded,
4:02
or form data and typically send it
through as the body of the request.
4:09
This hides the data from the URL but
still makes it available to the API.
4:14
You can use Postman to test
sending query parameters, headers,
4:19
and body data to any API you´re using.
4:24
Before we finish up with the request, I
wanna point out one more thing that we´ve
4:26
been requesting in our game example,
but you might have not have noticed.
4:31
Did you notice the v1 in
all of the URLs so far?
4:36
That's specifies the version
of the API that we're hitting.
4:39
We want to always provide
version numbers for our APIs.
4:43
And we want to make sure that the Legacy
APIs exist for as long as possible.
4:45
When your app comes out with
a brand new amazing version, and
4:52
you need a new API for it,
bump the version number up and
4:55
keep the old API around
as long as you can.
4:59
We all want users to use the latest and
greatest.
5:03
But upgrading a mobile app, or
a shell script, that only gets used a few
5:06
times a year, might not be something
our API's users can do right away.
5:10
The longer our API version sticks
around less the web breaks.
5:15
When consuming a third party API,
make sure you reference documentation for
5:20
the particular version you are using
as versions can vary greatly.
5:25
Also it's always a good idea to upgrade
to the latest API versions when possible.
5:29
Not only to get the latest and
greatest features, but
5:35
also to make sure that your application
continues to work as expected.
5:37
All right,
that's half the request response cycle.
5:42
Let's look at the other half and
5:45
how an API can provide more information to
its users than just a blob of JSON or XML.
5:46
You need to sign up for Treehouse in order to download course files.
Sign up