Requests5:53 with Alena Holligan
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
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