Designing REST APIs

00:00 Designing APIs

00:03 REST API design is a huge topic with many layers. As with most things in technology, there’s a wide range of opinions on the best approach to building APIs.

00:12 In this section, you’ll look at some recommended steps to follow as you build an API. The first step you’ll take as you build a REST API is to identify the resources the API will manage.

00:24 It’s common to describe these resources as plural nouns like customers, events, or transactions. As you identify different resources in your web service, you’ll build out a list of nouns that describe the different data users can manage in the API.

00:38 As you do this, make sure to consider any nested resources. For example, customers may have sales or events may contain guests. Establishing these resource hierarchies will help when you define API endpoints.

00:52 Once you’ve identified the resources in your web service, you’ll want to use these to define the API endpoints.

01:00 Here are some example endpoints for a transactions resource you might find in an API for a payment processing service.

01:08 These six endpoints cover all the operations that you’ll need to create, read, update, and delete transactions in the web service.

01:16 Each resource in your web service would have a similar list of endpoints based on what actions a user can perform with the API. An endpoint shouldn’t contain verbs.

01:27 Instead, you should select the appropriate HTTP methods to convey the endpoint’s action. For example, the endpoint seen here contains an unneeded verb. GET is included in the endpoint when it’s not needed.

01:40 The HTTP method GET already provides the semantic meaning for the endpoint by indicating the action so you can remove it from the endpoint. This endpoint contains only a plural noun and the HTTP method GET communicates the action.

01:55 Now take a look at an example of endpoints for a nested resource. Here you’ll see endpoints for guests that are nested under events resources. With these endpoints, you can manage guests for a specific event in the system.

02:09 This isn’t the only way to define an endpoint for nested resources. Some people prefer to use query strings to access a nested resource. A query string allows you to send additional parameters with your HTTP request.

02:22 In the endpoint seen on screen, you append a query string to get guests for a specific event ID. This endpoint will filter out any guests that don’t reference the given event ID.

02:34 As with many things in API design, you need to decide which method fits your web service best.

02:41 It’s very unlikely that your REST API will stay the same throughout the life of your web service. Resources will change and you’ll need to update your endpoints to reflect these changes.

02:51 This is where API versioning comes in. API versioning allows you to modify your API without fear of breaking existing integrations.

03:00 There’s a wide range of versioning strategies. Selecting the right option depends on the requirements of your API. On screen are some of the most popular options for API versioning. URI Versioning: Each time you modify the web API or change the schema of resources, you add a version number to the URI for each resource. HTTP Header Versioning: Here, you implement a custom header that indicates the version of the resource.

03:28 Query String Versioning: Rather than providing multiple URIs, you can specify the version of the resource by using a parameter within the query string appended to the HTTP request. Media Type Versioning: When a client application sends an HTTP GET request to a web server, it should stipulate the format of the content that it can handle. Regardless of which strategy you select, versioning your APIs is an important step to ensuring it can adapt to changing requirements while supporting existing users.

04:00 Now that you’ve covered endpoints, in the next section, you’ll look at some options for formatting data in your REST API and designing success and error responses.