Summary

We’ve come to the end of this course. But really, we’ve come to the beginning. As we learned from Donald Norman, we’re all engaged in our own action cycle, constantly looping between our goals and the world, crossing the bridges of execution and evaluation. Just like the web itself, we’re living out our lives in a repeating request-parse-wait loop and, with each cycle, we get to learn something new.

We hope this course has been a positive learning experience for you. The work of organizing our accumulated experiences and practices together in one place turned out to be a bigger project than expected and, at times, seemed to take on a life of its own. The resulting content between these lessons covers quite a bit of ground. So much that it’s worth it to briefly touch on the highlights before we finish.

Getting started

We started the course by visiting some important foundational concepts that can help us make sense of the way web APIs look and feel, along with how we can use the current technology to create them. We saw that APIs are meant to solve real business problems. Creating an API for the sake of creating an API isn’t enough. It’s important, as Kas Thomas says, to determine what our users expect to be able to do with APIs.

We also looked at the basic technology behind web APIs. The HTTP protocol defines how clients and servers communicate on the wire. The common practice of the web, as outlined by Tim Berners-Lee and others, sets the tone for how we should design APIs that live on the web. And Roy Fielding’s REST style establishes a repeatable set of constraints we can rely on when translating our API’s design into a fully working implementation.

The work of using protocols, practices, and a consistent style to solve real business problems for a target audience makes up the baseline by which we can judge all the APIs we plan to design and build going forward.

The design phase

In the design phase, we explored the processes of capturing the essence of the problem we need to solve and translating that into a consistent design ready for developers to use. We saw the power of Donald Norman’s action cycle as well as the importance of writing our API story and documenting the API workflow that captures the essence of the business problem. We covered the actual design process of identifying and detailing all the actions and properties of our API interface and learned how to document these API properties in a machine-readable, technology-agnostic way with the ALPS description format.

Above all, we learned that properly detailing and describing our API design sets the stage for a solid implementation that will meet the needs of both our business and our developer community.

The build phase

In the build phase, we learned to apply Frank Gehry’s sketching technique to APIs. We looked at the prototyping ideas offered by the garment-making practice of creating a toile to test a sewing pattern to explore the details of our API descriptions. These practices enable us to learn quickly and improve the chances of us building the right API without spending a lot of resources ahead of time.

Finally, we got to bring all our design and implementation work to a peak through the use of Node.js and the DARRT model to complete the coding of our fully functional API. We also learned that while the internal aspects of our API implementation (data properties and actions) are important, knowing how to map those internal elements to the external world through resources, representations, and transitions are the key to building a highly usable and loosely coupled API.

In the build phase, creating API sketches and prototypes helps us refine our understanding of the implementation details before we have to commit them to code.

The release phase

It wasn’t until the release phase that we got around to talking about testing and security. In real life, we’d constantly be iterating through design, build, test, and secure loops throughout the life of the API project.

In this part of the course, we discussed the power of SRTs (simple request tests) and Postman collections. We also explored the value of creating our own custom testing library using the Chai.js framework built into the Postman testing platform. We created our own command-line scripted interface for executing Postman test collections locally.

We covered the basics of message encryption, user identity, and access control. We also learned to use the Auth0 online platform for defining and supporting the security model for our APIs. Finally, we learned how to easily add machine-to-machine (M2M) access control with JSON Web Tokens (JWTs) and a small addition to the DARRT framework in Node.js.

With our API designed, built, tested, and secured, we then got to deploy it into production on the Heroku platform. Along the way, we explored the basics of deployment automation and learned about the differences between continuous integration, continuous delivery, and continuous deployment.

Lastly, we covered best practices for updating an API after it’s been released into production. We reviewed the Hippocratic oath for APIs (“first, do no harm”) and learned the three rules of designing and building nonbreaking changes: take nothing away, don’t redefine things, and make additions optional. We also explored decision-making around the use of side-by-side deployments and overwriting releases. Finally, to wrap it all up, we covered the proper way to permanently shut down an existing production API.

Releasing APIs is all about validating the API with testing, securing it properly, automating production releases, and safely and consistently updating APIs once they’ve been deployed into production.

Lastly, we covered best practices for updating an API after it’s been released into production. We reviewed the Hippocratic oath for APIs (“first, do no harm”) and learned the three rules of designing and building nonbreaking changes: take nothing away, don’t redefine things, and make additions optional. We also explored decision-making around the use of side-by-side deployments and overwriting releases. Finally, to wrap it all up, we covered the proper way to permanently shut down an existing production API.