1
00:00:00,430 --> 00:00:02,350
The request that a user sends in,

2
00:00:02,350 --> 00:00:07,180
can provide a lot more information
then just the endpoints and HTTP can.

3
00:00:08,210 --> 00:00:12,730
Different aspects of the request can be
used to change the format of the response.

4
00:00:12,730 --> 00:00:14,808
The version of the API and more.

5
00:00:14,808 --> 00:00:20,081
Let's open PostMan and
take a look at an actual request.

6
00:00:20,081 --> 00:00:22,044
You can close the launch screen for now,

7
00:00:22,044 --> 00:00:24,540
as we're going to be making
a very simple request.

8
00:00:25,670 --> 00:00:29,940
In the address bar, much like a web
browser, we can enter an endpoint url.

9
00:00:31,130 --> 00:00:35,760
We'll use the treehouse url plus add
the user name to get profile data.

10
00:00:40,510 --> 00:00:44,780
This will return an HTML
page as a user profile.

11
00:00:44,780 --> 00:00:46,650
We can preview just like a browser.

12
00:00:48,090 --> 00:00:56,420
If we add .json to the end We get
our profile data as JSON results.

13
00:00:56,420 --> 00:00:58,425
We can choose the Pretty format for
the JSON data

14
00:01:03,032 --> 00:01:06,510
We can send more information
to the API through parameters.

15
00:01:09,810 --> 00:01:15,200
By adding topic as the key and
security as the value,

16
00:01:15,200 --> 00:01:17,630
we can see these properties
are added to the URL.

17
00:01:19,730 --> 00:01:22,120
This is known as a query or query string.

18
00:01:23,680 --> 00:01:29,480
When we send this request, we will now see
only badges related to the security topic.

19
00:01:32,180 --> 00:01:37,320
Everything after the question mark is
treated as a set of key and value pairs.

20
00:01:37,320 --> 00:01:41,040
For example,
this query string gives us two keys.

21
00:01:41,040 --> 00:01:47,180
Order and sort, and two values,
desk for descending and points.

22
00:01:47,180 --> 00:01:50,900
Likely, this would cause us to
send back a collection of games

23
00:01:50,900 --> 00:01:53,610
sorted by their points
in descending order.

24
00:01:54,620 --> 00:01:57,820
There's nothing stopping you from
doing all of your extra work

25
00:01:57,820 --> 00:01:59,140
in the query stream.

26
00:01:59,140 --> 00:02:02,520
And many APIs handle their
requests in this way, but

27
00:02:02,520 --> 00:02:04,540
it's not always the best approach.

28
00:02:04,540 --> 00:02:09,240
For instance, what if you wanted to
let users request a record as either

29
00:02:09,240 --> 00:02:10,590
xml or json?

30
00:02:11,990 --> 00:02:14,880
In our tree house example
users can request the format

31
00:02:14,880 --> 00:02:17,100
by adding the .json to the end of the url.

32
00:02:18,270 --> 00:02:22,791
We could also send this information
using the HTTP headers.

33
00:02:25,870 --> 00:02:32,612
If the API accepts the format in a header,
you could send something like this,

34
00:02:32,612 --> 00:02:37,330
Accept as the key and
application/json as the value.

35
00:02:41,871 --> 00:02:44,690
And once again we see the JSON results.

36
00:02:44,690 --> 00:02:49,620
HTTP headers are one of the more amazing
and useful pieces to a great API.

37
00:02:51,520 --> 00:02:56,500
The HTTP spec provides a very
thorough list of headers that can and

38
00:02:56,500 --> 00:02:58,980
should be accepted by an API.

39
00:02:58,980 --> 00:03:01,830
You don't have to accept all of them,
of course, but

40
00:03:01,830 --> 00:03:04,920
let's look at a few that you should
probably always pay attention to.

41
00:03:06,160 --> 00:03:08,528
Accept, like we'd showed earlier,

42
00:03:08,528 --> 00:03:11,576
specifies the file format
the requester wants.

43
00:03:11,576 --> 00:03:16,220
Accept-Language specifies
the human-readable language, like English,

44
00:03:16,220 --> 00:03:17,463
Spanish, or Russian.

45
00:03:17,463 --> 00:03:21,500
Cache-Control is one you might
wanna be picky with, but

46
00:03:21,500 --> 00:03:25,350
it specifies whether the response
can be generated from a cache or

47
00:03:25,350 --> 00:03:27,980
a quick-to-access memory bank of data or
not.

48
00:03:29,250 --> 00:03:32,230
Again, you don't have to
implement all of the headers.

49
00:03:32,230 --> 00:03:34,370
You don't have to implement any of them.

50
00:03:34,370 --> 00:03:39,540
But smarter clients and smarter APIs
take advantage of the http spec,

51
00:03:39,540 --> 00:03:43,150
to make transactions cleaner and
more explicit.

52
00:03:43,150 --> 00:03:48,280
When consuming a third-party API make sure
you check the documentation to understand

53
00:03:48,280 --> 00:03:50,200
which headers that API accepts.

54
00:03:51,910 --> 00:03:54,970
You might be thinking that your user
will send all of their requests

55
00:03:54,970 --> 00:03:56,598
content to you in the query string.

56
00:03:56,598 --> 00:04:00,560
Most git endpoints accept parameters
through the query string

57
00:04:00,560 --> 00:04:02,810
where they are URL encoded.

58
00:04:02,810 --> 00:04:09,330
Post requests on the other hand encode the
content as either xwww form URLencoded,

59
00:04:09,330 --> 00:04:14,240
or form data and typically send it
through as the body of the request.

60
00:04:14,240 --> 00:04:19,240
This hides the data from the URL but
still makes it available to the API.

61
00:04:19,240 --> 00:04:24,029
You can use Postman to test
sending query parameters, headers,

62
00:04:24,029 --> 00:04:26,910
and body data to any API you´re using.

63
00:04:26,910 --> 00:04:31,827
Before we finish up with the request, I
wanna point out one more thing that we´ve

64
00:04:31,827 --> 00:04:36,401
been requesting in our game example,
but you might have not have noticed.

65
00:04:36,401 --> 00:04:39,920
Did you notice the v1 in
all of the URLs so far?

66
00:04:39,920 --> 00:04:43,134
That specifies the version
of the API that we're hitting.

67
00:04:43,134 --> 00:04:45,972
We want to always provide
version numbers for our APIs.

68
00:04:45,972 --> 00:04:52,090
And we want to make sure that the Legacy
APIs exist for as long as possible.

69
00:04:52,090 --> 00:04:55,590
When your app comes out with
a brand new amazing version, and

70
00:04:55,590 --> 00:04:59,260
you need a new API for it,
bump the version number up and

71
00:04:59,260 --> 00:05:01,880
keep the old API around
as long as you can.

72
00:05:03,260 --> 00:05:06,520
We all want users to use the latest and
greatest.

73
00:05:06,520 --> 00:05:10,370
But upgrading a mobile app, or
a shell script, that only gets used a few

74
00:05:10,370 --> 00:05:15,620
times a year, might not be something
our API's users can do right away.

75
00:05:15,620 --> 00:05:19,600
The longer our API version sticks
around less the web breaks.

76
00:05:20,630 --> 00:05:25,130
When consuming a third-party API,
make sure you reference documentation for

77
00:05:25,130 --> 00:05:29,600
the particular version you are using
as versions can vary greatly.

78
00:05:29,600 --> 00:05:35,080
Also it's always a good idea to upgrade
to the latest API versions when possible.

79
00:05:35,080 --> 00:05:37,810
Not only to get the latest and
greatest features, but

80
00:05:37,810 --> 00:05:41,180
also to make sure that your application
continues to work as expected.

81
00:05:42,530 --> 00:05:45,340
All right,
that's half the request-response cycle.

82
00:05:45,340 --> 00:05:46,900
Let's look at the other half and

83
00:05:46,900 --> 00:05:52,640
how an API can provide more information to
its users than just a blob of JSON or XML.