Design and Build Great Web APIs

Robust, Reliable, and Resilient

by Mike Amundsen

APIs are transforming the business world at an increasing pace. Gain the essential skills needed to quickly design, build, and deploy quality web APIs that are robust, reliable, and resilient. Go from initial design through prototyping and implementation to deployment of mission-critical APIs for your organization. Test, secure, and deploy your API with confidence and avoid the “release into production” panic. Tackle just about any API challenge with more than a dozen open-source utilities and common programming patterns you can apply right away.

Good API design means starting with the API-first principle—understanding who is using the API and what they want to do with it—and applying basic design skills to match customers’ needs while solving business-critical problems. Use the Sketch-Design-Build method to create reliable and scalable web APIs quickly and easily without a lot of risk to the day-to-day business operations. Create clear sequence diagrams, accurate specifications, and machine-readable API descriptions, all reviewed, tested, and ready to turn into fully-functional NodeJS code.

Create reliable test collections with Postman and implement proper identity and access control security with AuthO—without added cost or risk to the company. Deploy all of this to Heroku using a continuous delivery approach that pushes secure, well-tested code to your public servers, ready for use by both internal and external developers.

From design to code to test to deployment, unlock hidden business value and release stable and scalable web APIs that meet customer needs and solve important business problems in a consistent and reliable manner.

• Errata, typos, suggestions

• Source Code (zip file)

Releases:

• P1.0 2020/10/06
• B9.0 2020/09/23
• B8.0 2020/07/30
• B7.0 2020/06/05

Preface

• Getting Started
  • Getting Started with API First excerpt
    • Adopting the API-First Principle
    • Exploring APIs with curl
    • What’s Next?
    • Chapter Exercise
  • Understanding HTTP, REST, and APIs
    • Understanding Web API Protocols, Practices, and Styles
    • Managing Files with Git
    • What’s Next?
    • Chapter Exercise
• The Design Phase
  • Modeling APIs
    • Understanding Norman’s Action Lifecycle
    • Modeling Our Onboarding API Lifecycle
    • Managing Your Project with npm
    • What’s Next?
    • Chapter Exercise
  • Designing APIs excerpt
    • The Power of Design
    • The API Design Method
    • Identifying Your API Descriptors
    • Creating Your Sequence Diagram
    • What’s Next?
    • Chapter Exercise
  • Describing APIs
    • Learning the Role of Description Formats
    • Describing Your API with ALPS
    • Updating Your API Project
    • What’s Next?
    • Chapter Exercise
• The Build Phase
  • Sketching APIs excerpt
    • Learning from Frank Gehry’s Sketches
    • API Sketching Example
    • The Advantages of Sketching
    • Sketching APIs with Apiary Blueprint
    • API Sketching Tips and Tricks
    • What’s Next?
    • Chapter Exercise
  • Prototyping APIs
    • What Is an API Prototype?
    • API Prototyping with OpenAPI
    • Translating Your API Design into HTTP
    • Creating Your OpenAPI Document with SwaggerHub
    • Saving and Exporting Your API
    • Mocking Your API
    • Generating Your API Documentation
    • What’s Next?
    • Chapter Exercise
  • Building APIs
    • Defining the API Build Process
    • Relying on a Repeatable Process
    • Coding APIs with NodeJS and DARRT
    • Putting It All Together
    • What’s Next?
    • Chapter Exercise
• The Release Phase
  • Testing APIs
    • The Goals of API Testing
    • Testing with SRTs
    • Using Postman for API Testing
    • Running Tests Locally with Newman
    • What’s Next?
    • Chapter Exercise
  • Securing APIs
    • Understanding Security Basics
    • Implementing API Security with Auth0
    • Supporting Machine-to-Machine Security
    • What’s Next
    • Chapter Exercise
  • Deploying APIs
    • The Basics of Deployment Pipelines
    • The Role of DevOps
    • Deploying with Heroku
    • What’s Next?
    • Chapter Exercise
  • Modifying APIs
    • Going Beyond Versioning
    • The Three Rules for Safely Modifying APIs
    • The Recommended Pattern for Testing for API Changes
    • The Process for Safely Deploying APIs
    • Shutting Down an Existing API
    • What’s Next?
  • Some Parting Thoughts
    • Getting Started
    • The Design Phase
    • The Build Phase
    • The Release Phase
    • What’s Next?
• Appendixes
  • Installation Hints
    • curl
    • Git
    • GitHub and SSH
    • NodeJS and npm
    • Postman
    • Newman
    • Heroku Client
    • Installing the Local Utiltities
  • Exercise Solutions
    • Where’s the Code?
    • Solution for Chapter 1: Getting Started with API First
    • Solution for Chapter 2: Understanding HTTP, REST, and APIs
    • Solution for Chapter 3: Modeling APIs
    • Solution for Chapter 4: Designing APIs
    • Solution for Chapter 5: Describing APIs
    • Solution for Chapter 6: Sketching APIs
    • Solution for Chapter 7: Prototyping APIs
    • Solution for Chapter 8: Building APIs
    • Solution for Chapter 9: Testing APIs
    • Solution for Chapter 10: Securing APIs
    • Solution for Chapter 11: Deploying APIs
  • API Project Assets Checklist
    • Using the API Project Assets Checklist
    • Notes on the Assets Checklist
    • Your API Project Assets Checklist