Requests

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