Designing Data Exchange and Responses

00:00 Data Exchange and Response Design

00:04 Two popular options for formatting web service data are XML and JSON. Traditionally, XML was very popular with SOAP APIs, but JSON is more popular with REST APIs.

00:15 To compare the two, take a look at an example book resource formatted as XML and JSON. First, here’s the book formatted as XML.

00:27 XML uses a series of elements to encode data. Each element has an opening and closing tag with the data in between. Elements can be nested inside other elements.

00:37 You can see this on screen where several author tags are nested inside of authors.

00:44 Now take a look at the same book in JSON. JSON stores data in key-value pairs similar to a Python dictionary. Like XML, JSON supports nesting data to any level so you can model complex data.

00:57 Neither JSON nor XML is inherently better than the other, but there’s a preference for JSON amongst REST API developers. This is particularly true when you pair a REST API with a front-end framework, such as React or Vue.

01:12 Once you’ve picked a data format, the next step is to decide how you’ll respond to HTTP requests. All responses from your REST API should have a similar format and include the proper HTTP status code.

01:25 Here you’ll look at some example HTTP responses for a hypothetical API that manages an inventory of cars. These examples will give you a sense of how you should format your API responses.

01:37 To make things clear, you’ll look at raw HTTP requests and responses instead of using an HTTP library like requests. To start things off, take a look at a GET request to cars, which returns a list of cars.

01:52 This HTTP request is made up of four parts. GET is the HTTP method type, /cars is the API endpoint, HTTP/1.1 is the HTTP version, and Host is the API host. These four parts are all you need to send a GET request to cars.

02:14 Now take a look at the response. The API uses JSON as the data interchange format. The API returns a response that contains a list of cars. You know that the response was successful because of the 200 OK status code. The response also has a Content-Type header set to application/json.

02:35 This tells the user to parse the response as JSON. When you’re working with a real API, you’ll see more HTTP headers than seen on screen. These headers will differ between APIs, so they’ve been excluded here for clarity. It’s important to always set the correct Content-Type header on your response.

02:55 If you send JSON, then set Content-Type to application/json. If it’s XML, then set it to application/xml. This header tells the user how they should parse the data.

03:07 You also want to include an appropriate status code in your response. For any successful GET request, you should return 200 OK. This tells the user that their request was processed as expected.

03:21 Now, let’s take a look at another GET request, this time for a single car. This request queries the API for car 1.

03:30 On screen, you can see the response. This response contains a single JSON object with the car’s data. Since it’s a single object, it doesn’t need to be wrapped in a list. Like the last response, it also has a 200 OK status code.

03:47 Note that a GET request should never modify an existing resource. If the request contains data, then this data should be ignored, and the API should return the resource unchanged.

03:58 Next, a POST request to add a new car. This POST request includes JSON for the new car in the request. It sets the Content-Type header to application/json so the API knows the content type of the request.

04:12 The API will create a new car from the JSON.

04:16 On screen, you can see the response. This response has a 201 Created status code to tell the user that a new resource was created. Make sure to use 201 Created instead of 200 OK for all successful POST requests.

04:32 This response also includes a copy of the new car with an ID generated by the API. It’s important to send back an ID in the response so the user can modify the resource in the future.

04:43 It’s important to always send back a copy of a resource when a user creates it with POST or modifies it with PUT or PATCH. This way, the user can see the changes that they’ve made.

04:54 Next up, let’s look at a PUT request. This request uses the ID from the previous request to update the car with all new data. As a reminder, PUT updates all fields on the resource with new data.

05:09 On screen, you can see the response. This response includes a copy of the car with the new data. Again, you always want to send back the full resource for a PUT request.

05:20 The same applies for a PATCH request. Here, performing the slightly legally dubious action of changing the car’s VIN and color. PATCH requests only update a part of a resource.

05:32 In the request on screen, the VIN and color fields will be updated with the new values.

05:38 Here’s the response. The response contains a full copy of the car. As you can see, only the VIN and color fields have been updated. Finally, let’s take a look at how your REST API should respond when it receives a DELETE request.

05:55 Here’s a DELETE request to remove a car.

05:59 The DELETE request tells the API to remove the car with ID four. On screen, you can see the response. The response only includes the status code 204 No Content.

06:11 The status code tells the user that the operation was successful, but no content was returned in the response. This makes sense since the car has been deleted, there’s no reason to send a copy of it back in the response. Responses just seen work well when everything goes as planned, but what happens if there’s a problem with the request?

06:31 In the next section, you’ll look at how your REST API should respond when errors occur.