Designing Error Responses

00:00 Designing Error Responses

00:03 There’s always a chance that a request to your REST API could fail. It’s a good idea to define what an error response will look like. These responses should include a description of what error occurred along with the appropriate status code.

00:17 To start, look at a request for a resource that doesn’t exist in the API. Here, the user sends a GET request to /motorcycles, which doesn’t exist.

00:27 The API sends back the response seen on screen. It includes a 404 Not Found status code. Along with this, the response contains a JSON object with a descriptive error message.

00:39 Providing this message gives the user more context for the error.

00:44 Next, take a look at the error response when the user sends an invalid request. This POST requests JSON, but it isn’t formatted correctly. It’s missing a closing curly brace at the end. The API won’t be able to process this data.

00:58 The error response seen on screen tells the user about the issue. This response includes a descriptive error message along with the 400 Bad Request status code telling the user that they need to fix the request.

01:12 There are several other ways that the request can be wrong, even if it’s formatted properly. In this example, the user sends a POST request but includes an unsupported media type.

01:24 Here, the user sends XML, but the API only supports JSON.

01:29 The API responds with this. The response includes the 415 Unsupported Media Type status code to indicate that the POST request included a data format that’s not supported by the API.

01:42 This error code makes sense for data that’s in the wrong format but what about data that’s invalid, even if it’s in the correct format?

01:49 Here, the user sends a POST request but includes car data that doesn’t match fields of the other data.

01:56 Here, the user adds topSpeed and warrantyLength fields to the JSON. These fields aren’t supported by the API, so it responds with this error message.

02:06 This includes the 422 Unprocessable Entity status code. This status code indicates that there weren’t any issues with the request, but the data was invalid.

02:16 A REST API needs to validate incoming data. If the user sends data with the request, then the API should validate the data and inform the user of any errors.

02:26 Responding to requests, both successful and erroneous, is one of the most important jobs of a REST API. If your API is intuitive and provides accurate responses, it will be easier for users to build applications around your web service.

02:40 Luckily, some great Python web frameworks abstract away the complexities of processing HTTP requests and returning responses, and you’ll look at them in the next sections of the course.