Goal of this course

This course is meant for software developers and designers who are looking to quickly get up to speed on how to design and build web APIs. Because the content is based on training material that’s been used over the years, this course may come in handy if you decide to put together your own API training course for your team or company.

How is this course organized?

The course is organized into five chapters: “Getting Started,” “The Design Phase,” “The Build Phase,” “The Release Phase,” and “Appendixes.” Each chapter marks a key set of skills—from thinking about APIs to actually getting them up and running in production. The following is a quick summary of each of the five chapters of this course.

Getting started

The first chapter helps set the foundation for the world of APIs. First explore what it means to adopt an “API-first” approach to designing and building APIs. Then, we get some background on the existing services we’ll be working with and our plan for implementing an API. In the second chapter, we spend time exploring the basics of the protocols and practices commonly used to create APIs, including the HTTP protocol and the REST style for creating services that run on HTTP.

The design phase

Here, we focus on the process of modeling, designing, and describing our API. Along the way, we look at tools to help us model and visualize the API, as well as the ones that help us create a machine-readable description that can be used to produce our final API.

The build phase

The build phase of API development is all about converting our well-designed and well-described API into working code. In this part, we take a three-step approach—sketching, prototyping, and finally building the API itself. We use the Apiary Blueprint format for sketches, the Open API Specification (also known as Swagger) to create the exact definition, and finally, we use Node.js and a custom framework called DARRT to turn the Swagger spec into working code.

The release phase

In the release phase, we look at how to test, secure, and deploy our completed API to the cloud. To do this, we’ll use the local Postman platform for testing and the Auth0 cloud service for authentication and access control. Then, we’ll release the finished API onto the Heroku public cloud.

Once we know that all is working as expected, we look at how to introduce minor changes to our production API without breaking any existing API consumers.

Straight-line approach

While the course takes a very linear approach to all this (from modeling to building to releasing the API), in reality API development involves lots of iteration and bouncing back and forth between skills. In most production work, we end up working in a series of loops. These allow us to first model, then design, then go back and fix the model a bit, then design some more, and so on until we finally get to the point where our API is ready to be released to the cloud.

While looping is the right way to do this work, it isn’t necessarily the best approach for a course about it. For that reason, we’ll stick to our linear approach from start to finish, with lots of reminders along the way about iteration and looping as a key element in designing and building great APIs.

What does this course cover?

The goal of this course is to give comprehensive front-to-back coverage of what’s required to get a new API up and running in production. We’ll cover the skills needed to create RESTful APIs. These are HTTP-based APIs that rely on the common request-response style used by the vast majority of APIs on the web today. There are other important API styles (such as gRPC and GraphQL) that we won’t be able to cover in this course. The good news is that most other API styles rely on the HTTP-based web API approach, which we’ll cover in this course. Getting a solid understanding of RESTful APIs will come in handy if you want to explore other styles in the future.

The topic of web APIs is quite large, and we won’t be able to cover everything. This course focuses on a series of steps centered around the external interfaces (the APIs) used to access back-end services. However, we won’t be getting into how to build and deploy back-end services (sometimes called microservices). We also won’t be covering the details of writing client applications that consume web APIs. Finally, we won’t be covering topics related to the broader aspects of API management.

About the sample project: BigCo, Inc.

In this course, we’ll be helping a fictitious company called BigCo Inc. modernize its process of bringing on new customers by designing, building, and deploying a brand-new API called the Onboarding API. The company’s onboarding process is still handled mostly by people filling in forms and then adding data to several standalone applications running in the company’s network. Our job will be to learn how BigCo currently handles their customer onboarding process. Then, we’ll convert that into an API design and—using existing services already in place—implement a single onboarding API that handles all the steps currently handled by BigCo staff.

About BigCo Inc.: The Bayesian International Group of Companies (BigCo) Inc. is a fictitious company that we’ll use in the examples of this course. For a while, it was a manufacturer of important turn-of-the-century technologies, including mobile x-ray machines and hydrophones. BigCo also played an instrumental role in helping to establish fields of study in the modern computer era, including predictive algorithms and robotics controls. Currently, BigCo products focus on inverse probability problems and how they can be used to help improve decisions and policy-making in both the private and public sectors.

Along the way, we’ll take a look at the basics of API design as well as how to produce and document our design in a consistent way so that it’s understood by both BigCo onboarding staff and developers. We’ll also look at how to use a simple three-stage process (sketch, prototype, and build) for converting an API design into running code. And once the code is available, we’ll work through the release process of testing, securing, and deploying the working Onboarding API. Finally, we’ll take a look at what it takes to make updates to an already released API without breaking any of the applications currently using it.