WIXLIB

There are quite a few HTTP headers that clients and servers deal with,so we will wait to talk about other ones until they are relevant in laterchapters.BodyThe request body contains the data the client wants to send the server.Continuing our pizza ordering example above, the body is where theorder details go.A unique trait about the body is that the client has complete controlover this part of the request. Unlike the method, URL, or headers,where the HTTP protocol requires a rigid structure, the body allows theclient to send anything it needs.These four pieces — URL, method, headers, and body — make up acomplete HTTP request.

Figure 2. The structure of an HTTP request.HTTP ResponsesAfter the server receives a request from the client, it attempts to fulfillthe request and send the client back a response. HTTP responses havea very similar structure to requests. The main difference is that insteadof a method and a URL, the response includes a status code. Beyondthat, the response headers and body follow the same format asrequests.

Status CodesStatus codes are three-digit numbers that each have a unique meaning.When used correctly in an API, this little number can communicate a lotof info to the client. For example, you may have seen this page duringyour internet wanderings:Figure 3. A default 404 web page.The status code behind this response is 404, which means "Not Found."Whenever the client makes a request for a resource that does not exist,the server responds with a 404 status code to let the client know: "thatresource doesn't exist, so please don't ask for it again!"There is a slew of other statuses in the HTTP protocol, including 200("success! that request was good") to 503 ("our website/API is currentlydown.") We'll learn a few more of them as they come up in laterchapters.After a response is delivered to the client, the Request-Response Cycleis completed and that round of communication over. It is now up to theclient to initiate any further interactions. The server will not send theclient any more data until it receives a new request.

Figure 4. The structure of an HTTP response.How APIs Build on HTTPBy now, you can see that HTTP supports a wide range of permutationsto help the client and server talk. So, how does this help us with APIs?The flexibility of HTTP means that APIs built on it can provide clientswith a lot of business potential. We saw that potential in the pizzaordering example above. A simple tweak to the request method wasthe difference between telling the server to create a new order orcancel an existing one. It was easy to turn the desired businessoutcome into an instruction the server could understand. Verypowerful!

This versatility in the HTTP protocol extends to other parts of a request,too. Some APIs require a particular header, while others require specificinformation inside the request body. Being able to use APIs hinges onknowing how to make the correct HTTP request to get the result youwant.Chapter 2 RecapThe goal of this chapter was to give you a basic understanding of HTTP.The key concept was the Request-Response Cycle, which we brokedown into the following parts: Request - consists of a URL (http:// ), a method (GET, POST, PUT,DELETE), a list of headers (User-Agent ), and a body (data). Response - consists of a status code (200, 404 ), a list of headers,and a body.Throughout the rest of the course, we will revisit these fundamentals aswe discover how APIs rely on them to deliver power and flexibility.HomeworkUse the form on the site for Chapter 2 to make the following list ofrequests and see what responses you are given.Instructions

1Send a GET request without any body data.2Send a POST request and type your favorite kind of pizza in thebody field.3Send a PUT request and type a new ingredient to add to yourpizza in the body field.4Send a DELETE request without any body data.NextIn the next chapter, we explore what kind of data APIs pass betweenthe client and the server.NOTES1. The HTTP specification actually requires a request to have a URI(Universal Resource Identifier), of which URLs are a subset, along with URNs(Uniform Resource Names). We chose URL because it is the acronym readersalready know. The subtle differences between these three are beyond thescope of the course.

So far, we've learned that HTTP (Hyper-Text Transfer Protocol) is theunderpinning of APIs on the web and that to use them, we need toknow how HTTP works. In this chapter, we explore the data APIsprovide, how it's formatted, and how HTTP makes it possible.Representing DataWhen sharing data with people, the possibilities for how to display theinformation is limited only by human imagination. Recall the pizzaparlor from last chapter — how might they format their menu? It couldbe a text-only, bulleted list; it could be a series of photos with captions;or it could even be only photos, which foreign patrons could point at toplace their order.A well-designed format is dictated by what makes theinformation the easiest for the intended audience tounderstand.The same principle applies when sharing data between computers. Onecomputer has to put the data in a format that the other willunderstand. Generally, this means some kind of text format. The most

common formats found in modern APIs are JSON (JavaScript ObjectNotation) and XML (Extensible Markup Language).JSONMany new APIs have adopted JSON as a format because it's built on thepopular Javascript programming language, which is ubiquitous on theweb and usable on both the front- and back-end of a web app orservice. JSON is a very simple format that has two pieces: keys andvalues. Keys represent an attribute about the object being described. Apizza order can be an object. It has attributes (keys), such as crust type,toppings, and order status. These attributes have corresponding values(thick crust, pepperoni, and out-for-delivery).Let's see how this pizza order could look in JSON:{"crust": "original","toppings": ["cheese", "pepperoni", "garlic"],"status": "cooking"}In the JSON example above, the keys are the words on the left:toppings, crust, and status. They tell us what attributes the pizza ordercontains. The values are the parts to the right. These are the actualdetails of the order.

Figure 1. JSON key and value.If you read a line from left to right, you get a fairly natural Englishsentence. Taking the first line as an example, we could read it as, "thecrust for this pizza is original style." The second line can also be read —in JSON, a value that starts and ends with square brackets ([]) is a list ofvalues. So, we read the second line of the order as, "the toppings forthis order are: cheese, pepperoni, and garlic."Sometimes, you want to use an object as the value for a key. Let'sextend our pizza order with customer details so you can see what thismight look like:{"crust": "original","toppings": ["cheese", "pepperoni", "garlic"],"status": "cooking","customer": {"name": "Brian","phone": "573-111-1111"

}}In this updated version, we see that a new key, "customer", is added.The value for this key is another set of keys and values that providedetails about the customer that placed the order. Cool trick, huh?! Thisis called an Associative Array. Don't let the technical term intimidate youthough - an associative array is just a nested object.XMLXML has been around since 1996 1. With age, it has become a verymature and powerful data format. Like JSON, XML provides a fewsimple building blocks that API makers use to structure their data. Themain block is called a node.Let's see what our pizza order might look like in XML: order crust original /crust toppings topping cheese /topping topping pepperoni /topping topping garlic /topping /toppings status cooking /status

/order XML always starts with a root node, which in our pizza example is"order." Inside the order are more "child" nodes. The name of eachnode tells us the attribute of the order (like the key in JSON) and thedata inside is the actual detail (like the value in JSON).Figure 2. XML node and value.You can also infer English sentences by reading XML. Looking at the linewith "crust", we could read, "the crust for the pizza is original style."Notice how in XML, every item in the list of toppings is wrapped by anode. You can see how the XML format requires a lot more text tocommunicate than JSON does.How Data Formats Are Used In HTTPNow that we've explored some available data formats, we need to knowhow to use them in HTTP. To do so, we will say hello again to one of thefundamentals of HTTP: headers. In Chapter 2, we learned that headersare a list of information about a request or response. There is a headerfor saying what format the data is in: Content-Type.When the client sends the Content-Type header in a request, it is tellingthe server that the data in the body of the request is formatted a

particular way. If the client wants to send the server JSON data, it willset the Content-Type to "application/json." Upon receiving the requestand seeing that Content-Type, the server will first check if itunderstands that format, and, if so, it will know how to read the data.Likewise, when the server sends the client a response, it will also set theContent-Type to tell the client how to read the body of the response.Sometimes, the client can only speak one data format. If the serversends back anything other than that format, the client will fail andthrow an error. Fortunately, a second HTTP header comes to therescue. The client can set the Accept header to tell the server what dataformats it is able to accept. If the client can only speak JSON, it can setthe Accept header to "application/json." The server will then send backits response in JSON. If the server doesn't support the format the clientrequests, it can send back an error to the client to let it know therequest is not going to work.With these two headers, Content-Type and Accept, the client and servercan work with the data formats they understand and need to workproperly.Figure 3. Data format headers.

Chapter 3 RecapIn this chapter, we learned that for two computers to communicate,they need to be able to understand the data format passed to them.We were introduced to 2 common data formats used by APIs, JSON andXML. We also learned that the Content-Type HTTP header is a usefulway to specify what data format is being sent in a request and theAccept header specifies the requested format for a response.The key terms we learned were: JSON: JavaScript Object Notation Object: a thing or noun (person, pizza order.) Key: an attribute about an object (color, toppings.) Value: the value of an attribute (blue, pepperoni.) Associative array: a nested object XML: Extensible Markup LanguageHomeworkUse the form in our site for Chapter 3 to make the following list ofrequests and see what responses you are given.Instructions1Send a request with: Content-Type header "application/json",Accept header "application/json", and data format "XML".

2Send a request with: Content-Type header "application/json",Accept header "application/json", and data format "JSON".3Ok, now just try changing things around and seeing whathappens! :)NextIn the next chapter, we find out how two computers can establish trustusing Authentication in order to pass along sensitive data, like customerdetails or private content.Notes:1. http://en.wikipedia.org/wiki/XML

Things are starting to pick up in our understanding of APIs. We knowwho the client and server are, we know they use HTTP to talk to eachother, and we know they speak in specific data formats to understandeach other. Knowing how to talk, though, leaves an important question:how does the server know the client is who it claims to be? In thischapter, we explore two ways that the client can prove its identity to theserver.Identities in a Virtual WorldYou've probably registered for an account on a website before. Theprocess involves the site asking you for some personal information,most notably a username and a password. These two pieces ofinformation become your identifying marks. We call these yourcredentials. When you visit the website again, you can login byproviding these credentials.Logging-in with a username and password is one example of a technicalprocess known as authentication. When you authenticate with aserver, you prove your identity to the server by telling it informationthat only you know (at least we hope only you know it). Once the serverknows who you are, it can trust you and divulge the private data in youraccount.

There are several techniques APIs use to authenticate a client. Theseare called authentication schemes. Let's take a look at two of theseschemes now.Basic AuthenticationThe logging-in example above is the most basic form of authentication.In fact, the official name for it is Basic Authentication ("Basic Auth" toits friends). Though the name has not garnered any creativity awards,the scheme is a perfectly acceptable way for the server to authenticatethe client in an API.Basic Auth only requires a username and password. The client takesthese two credentials, smooshes them together to form a single value 1,and passes that along in the request in an HTTP header calledAuthorization.

Figure 1. The Authorization HTTP header.When the server receives the request, it looks at the Authorizationheader and compares it to the credentials it has stored. If the usernameand password match one of the users in the server's list, the serverfulfills the client's request as that user. If there is no match, the serverreturns a special status code (401) to let the client know thatauthentication failed and the request is denied.Though Basic Auth is a valid authentication scheme, the fact that it usessame username and password to access the API and manage theaccount is not ideal. That is like a hotel handing a guest the keys to thewhole building rather than to a room.

Similarly with APIs, there may be times when the client should havedifferent permissions than the account owner. Take for example abusiness owner who hires a contractor to write a program that uses anAPI on their behalf. Trusting the contractor with the account credentialsputs the owner at risk because an unscrupulous contractor couldchange the password, locking the business owner out of their ownaccount. Clearly, it would be nice to have an alternative.API Key AuthenticationAPI Key authentication is a technique that overcomes the weakness ofusing shared credentials by requiring the API to be accessed with aunique key. In this scheme, the key is usually a long series of letters andnumbers that is distinct from the account owner's login password. Theowner gives the key to the client, very much like a hotel gives a guest akey to a single room.When the client authenticates with the API key, the server knows toallow the client access to data, but now has the option to limitadministrative functions, like changing passwords or deleting accounts.Sometimes, keys are used simply so the user does not have to give out

their password. The flexibility is there with API Key authentication tolimit control as well as protect user passwords.So, where does the API key go? There is a header for it, too, right?Unfortunately, there is not. Unlike Basic Auth, which is an establishedstandard with strict rules, API keys were conceived at multiplecompanies in the early days of the web. As a result, API keyauthentication is a bit like the wild west; everybody has their own wayof doing it.Over time, however, a few common approaches have emerged. One isto have the client put the key in the Authorization header, in lieu of ausername and password. Another is to add the key onto the URL(http://example.com?api key my secret key). Less common is to burythe key somewhere in the request body next to the data. Wherever thekey goes, the effect is the same - it lets the server authenticate theclient.Chapter 4 RecapIn this chapter, we learned how the client can prove its identity to theserver, a process known as authentication. We looked at twotechniques, or schemes, APIs use to authenticate.The key terms we learned were: Authentication: process of the client proving its identity to theserver Credentials: secret pieces of info used to prove the client'sidentity (username, password.)

Basic Auth: scheme that uses an encoded username andpassword for credentials API Key Auth: scheme that uses a unique key for credentials Authorization Header: the HTTP header used to hold credentialsHomeworkUse the form in our site for Chapter 4 below to explore locations usingthe Google Maps API.

NextIn the next chapter, we continue the discussion of authentication bylooking at a third technique; one that is quickly becoming the standardof the web.1. The actual process involves combining the username with a colon,followed by the password, and then running the whole string through thebase64 encoding algorithm. Thus "user" and "password" becomes"user:password" and, after encoding, you have "dXNlcjpwYXNzd29yZAo ".

In Chapter 4, we mentioned most websites use a username andpassword for authentication credentials. We also discussed how reusingthese credentials for API access is insecure, so APIs often require adifferent set of credentials from the ones used to login to the website. Acommon example is API keys. In this chapter, we look at anothersolution, Open Authorization (OAuth), which is becoming the mostwidely used authentication scheme on the web.Making Life Easy for PeopleHave you ever had to complete a registration form like the one below?

Figure 1. A product key as seen on Microsoft's Windows 8 registration form.Typing a long key into a form field like the one above makes for a pooruser-experience. First, you have to find the required the key. Sure, itwas right in your inbox when you bought the software, but a year later,you're scrambling to find it (What email was it sent from? Which emaildid I use to register?!) Once located, you have to enter the darned thingperfectly - making a typo or missing a single character will result infail

2. Adam DuVander, API Growth Doubles in 2010, Social and Mobile are Trends . ProgrammableWeb. January 3, 2011. 3. Technically, an API is just a set of rules (interface) that the two sides agree to follow. The company publishing the API then implements their side by writing a pro