Building APIs is hard. Many teams have stumbled into the challenges of writing an API that effectively communicates its intent. APIs are often not resilient, performant, or discoverable. This is especially common when the team homegrows its own specification and patterns.
RESTfully building an API over HTTP can let us stand on the shoulders of giants. We can follow guidelines that create easy-to-use APIs. REST also exposes us to edge cases we may not have known about. When we build RESTfully, we can take full advantage of tooling that has been built around the HTTP specification.
This course will help you understand the basics of RESTful services over HTTP, as well as the advanced features your team can make use of. You will learn why REST and HTTP are popular API specifications, and you will learn how to document your API such that it is lightweight and easy for your consumers to understand.
This is an engaging workshop, not just a lecture. Your instructor will split you into groups and in many sections; you will use some lightweight tooling to build your own sample API as you follow along with the course.
This course is language agnostic and can be customized to fit your team’s needs. For more on custom course content, get in touch with us by clicking the “Have a Learning Advisor Contact Me” button on the left-hand side of your screen.
- Upcoming Dates and Locations
Guaranteed To Run
- Course Outline
Part 1: Introduction
- REST or ...?
- A look at gRPC for action-based services.
- GraphQL:A query-focused paradigm.
- REST: This is what the course is about. REST shines when you have external customers or low-touch internal consumers. It is useful when you want to ensure your customers are not surprised by weird, homegrown logic.
Exercise: With guidance from Phil Sturgeon’s API Decision Diagram, think about for which paradigm your software system would be a good fit.
- OpenApi 3 as a service model.
- JSON Schema as a data model.
- SwaggerEditor for online editing.
- ReDoc for making your exercise specs look good.
Exercise: Come up with a business domain for which to make an API. Create a new specification and add a basic description of it.
Part 2: Building Blocks
- Resources: The Foundation
- What is a resource?
- The hidden gem: URIs.
- More resources, fewer actions.
Exercise: Come up with a few key resources you think are important to your chosen business domain. Record them and agree on a way to identify them in a URI. Record what information is important for each resource.
- The Art of Negotiation
- Resources have representations.
- There are good ways and bad ways to negotiate content.
Exercise: Look at your resources and think about how much information is in them. What content type might be best to show them?
- GETting resources.
Exercise: Add GET endpoints in your OpenAPI spec file for each resource. Write up what the schema might look like for a 200 response.
- Understanding POST/PUT/DELETE.
Exercise: Choose at least one of your resources. Think about what each of these methods would mean for that resource, or if it makes sense. Record them into your OpenAPI spec. Think about what data the user might like to get back in a response.
Exercise: Discuss whether any of these lesser-known methods are useful for your chosen resources.
- What REST is intended to be about?
- Start with an entry point.
- Standard links to think about.
Exercise: Discuss whether any of your current resources are connected. If so, write some links in their responses. If not, create a new resource in your spec and link to it.
- What's the (HTTP) Status?
- 2xx Status Codes: The different variances of success.
- 3xx Status Codes: When we need to move things around.
- 4xx Status Codes: Where the user did something not quite right.
- 5xx Status Codes: Where the server is having...difficulties.
Exercise: Think about what edge cases may exist for one or more of your resources. Match some of them to an appropriate status code and record it in your spec.
Part 3: Things You Can Do With a RESTful API
- Basic authentication.
- Oauth 2 as a way to get other orgs to do work for you.
- Always use HTTPS.
Exercise: Fill out the authentication part of your spec based on the instructor-provided Oauth server.
- Server-specified, client-obeyed.
- Some cache headers, like expires and cache-control.
- What to cache.
Exercise: Pick at least one of your resources to cache. Figure out how you want to cache it for best usability and record it the headers in your spec.
- Be optimistic about conflicts.
- Etag as a version number.
Exercise: Think about a resource (existing or new) for which you may want to provide optimistic concurrency. Add the appropriate headers to the spec.
- Why you should evolve, not version.
- Evolving endpoints.
- Evolving fields.
Exercise: Choose either a resource or a couple fields in a resource you want to deprecate and replace with something better. Record in the spec the new fields/resource to which you want to transition.
- Who should attend
- Developers and programmers
- System architects
- System administrators
- DevOps practitioners
- IT Operations Staff