Examine HTTP Message Bodies
The body of an HTTP request or response can serve many functions, from including the input data to a POST request, to returning varied representations of a resource in response to a GET request. This lesson details how message bodies are handled in requests and responses, and the associated HTTP headers that provide metadata about the included message body.
[00:00] Whenever an HTTP response includes the message body, there will be a header, Content-Type, that lets the client know what the specific type of content returned in that message body is.
[00:15] In this case, the GitHub API has returned us some JSON describing this .gitignore template. You can see this encoded in our Content-Type header, along with a parameter specifying the specific character set included in our response.
[00:31] If we take a look at our request, you can see the client has specified, using the Accept header, that it can accept any kind of Content-Type in the response.
[00:42] If we had been explicit about our Content-Type we wanted to accept, we can see that our Accept header of application JSON can still be satisfied by the server, and the same content and Content-Type will be returned.
[01:01] Many APIS will allow you to request the same resource with a different Content-Type that can also be provided. For the GitHub API, if we ask for vin.github.v3.raw, the API will return the raw .gitignore template in our response.
[01:21] You can see, instead of JSON encoded, we have a raw .gitignore file. The Content-Type is updated to reflect that, to show that instead of returning us JSON, now this exact same resource is returning us this GitHub raw Content-Type.
[01:41] This Accept header is how we let the server know what Content-Type we wanted. Using Accept headers in this manner is referred to as content negotiation, because we've negotiated specifically the Content-Type our client would like to get returned.
[01:57] Sometimes, we might request a certain Content-Type that this particular resource can't provide. Here, we've said we would only like to accept text/HTML for this particular resource, but because the GitHub API doesn't know how to return this resource in that media type, it's returned us a 415 status code saying that it's an unsupported media type. It can't return this resource as HTML.
[02:24] Much like HTTP responses include a Content-Type to specify the type of their message body, HTTP requests that include a message body also include some Content-Type headers. Let's take a look at creating a GitHub issue.
[02:45] In this case, we use JSON for the request Content-Type by passing in "-j." Our server has responded to our request. Let's take a look at that. Here, our request now has a message body. Because that message body has been coded as JSON, you can see that the Content-Type of our request is included as application JSON.
[03:15] Because the GitHub server understands how to accept requests with JSON-encoded content, it went ahead and created our issue for us, much like sending a JSON request to our resource.
[03:28] We could also send a form-urlencoded request. Here, we can see our request Content-Type is now listed as application form-urlencoded, and the request body is encoded to match.
[03:47] In this case, though, our server, the GitHub API, does not understand how to accept form-urlencoded requests at our particular resource, and it's let us know that by returning a 400 Bad Request response. This is synonymous to sending an Accept header in a Git request with a Content-Type that the server cannot provide.
[04:08] In this case, we're sending a Content-Type in our message body request that the server can't accept, and so a Bad Request response is returned.