16. Continuing the API Design Journey

When done effectively, governance can provide clear direction, remove obstacles, and allow different parts of the organization to function independently.

Matt McLarty

An organization that produces more than one API product must learn to scale their API design process. Otherwise, designs will lack consistency across the portfolio of APIs produced by the organization. Authentication and authorization will vary between APIs. Naming conventions and error responses will deviate. In short, the API program will become a mess.

This chapter explores the factors required to scale API design efforts within an organization. These factors include establishing a style guide for consistency, incorporating design reviews, and encouraging a culture of reuse. Once applied, teams will be able to function independently while maintaining consistency across the API portfolio. Finally, the chapter takes a look back at the topics covered in this book and offers some guidance on how to continue the API design journey.

Establishing an API Style Guide

Many API programs begin as a single API or a few, small APIs. Over time, more APIs emerge across the company. Consistency for all API consumers is an important component of a great developer experience. A common design approach makes integration more intuitive and can reduce troubleshooting and support costs.

Great style guides go beyond basic design decisions to include common error strategies, applying patterns consistently across APIs, and even suggest common architecture styles for teams looking to get started quickly.

An API style guide commonly includes the following topics:

■ Introduction – the scope of the style guide, who to contact for questions, clarifications, or enhancements

■ API fundamentals – used to educate and coach those less familiar with the basics. This may consist of links to internal or external training materials

■ Standards – naming conventions, guidance for selecting HTTP methods and response codes, organizing resource paths, resource lifecycle design, payload and content formats, when and how to use hypermedia

■ Design patterns – common patterns encountered, including: pagination, error responses, bulk processing, singleton resources

■ Lifecycle management – recommendations for moving an API into production, along with deprecation and sunset procedures

■ Tools and technologies – list of tools that are recommended, including those with site licenses already available

■ Operational recommendations – recommended API management tools, configurations, processes, marketing recommendations, and common practices for highly available, robust, and resilient APIs

■ Further reading – additional resources that may be interesting to the reader, including both internal and publicly available papers, articles, and videos

Too often, style guides are used to push an agenda. Full compliance, or else. That isn’t what style guides should be about. Their goal should be to advise teams designing APIs toward a more consistent API with other APIs across the organization. A newly hired developer should be able to work with a variety of APIs across the organization without realizing that different teams designed them.

Methods for Encouraging Style Guide Adherence

Style guides, without some kind of incentive to adhere to the recommendations, will be ignored. There are three common methods to enforcing style guide compliance:

1. Incentivized – a centralized team oversees and enforces the guide. Reviews are conducted by the centralized team for any new API, prior to production deployment. API teams are incentivized to adhere to the style guide to gain access to shared services and support rather than being forced to implement it themselves, e.g. API management layer, operational and infrastructure support

2. Federated – a centralized team oversees and maintains the style guide, but coaches embedded locally within the business unit and/or region are available to address their specific needs. This avoids the ivory tower problem of a committee designing standards without understanding the needs of specific business units

3. Clone and Customize – A single group manages the style guide. Teams clone the standards as a starting point, making minor enhancements locally for business unit consistency. For organizations that have many, independent teams within and/or across business units, this is the most effective method

These methods may be used independently or in combination to achieve the desired results that best meet the needs of the organization.

Selecting Style Guide Tone

Some style guides are informal, while others are very formal including the use of RFC 2119 for requirement levels. Deciding upon a tone and formality for the style guide depends upon the answers to three questions:

■ Will the organization be enforcing the standard? If so, then use RFC 2119 recommendations to enforce what MUST, SHOULD, and MAY be implemented

■ Will enforcement be deferred to a future date? Then go ahead and start using RFC 2119, but keep the wording to lowercase, e.g., must, should, may, until it is enforced. This demonstrates expectations and likely future enforcement, but with less of a formality during the initial introductory period

■ Is the guide shared across business units for which the organization will have no control over, or cannot strictly enforce? Then soften the tone and focus on design consistency by encouraging teams to adopt as many of the guidelines as possible, rather than using a more formal tone

Tips for Getting Started with an API Style Guide

■ Browse Arnaud Lauret’s (aka the API Handyman) API Stylebook. The API Stylebook aims to help API Designers to solve API design matters and build their API design guidelines. Browse other publicly available style guides as well for insights

■ Start small. The scope of an API style guide may be too much to take on initially by one individual or a small team. Start simple and expand over time

■ Socialize the style guide. Just because the style guide exists doesn’t mean people in the organization know about it. Spend time evangelizing the style guide with teams. Gain their insights from early release candidates, before releasing an official version.

Remember

The goal of an API style guide is to advise teams designing APIs toward consistency with other APIs across the organization.

Supporting Multiple API Styles

While most organizations may suggest or mandate a single API style, this won’t always be the case. As new API styles emerge, API portfolios become challenged with the push for new ways of interacting with the enterprise. Remember, it was only a decade ago that most organizations stopped developing SOAP-based web services. API programs must consider how new API styles will be evaluated, approved, and supported as they gain popularity.

API programs must consider async APIs, such as Webhooks, WebSockets, SSE, data streaming, and internal messaging as part of the API portfolio. Like synchronous APIs, the design of async APIs must be governed and managed as part of the overall API portfolio.

The API style guide will need to address each of these API styles as they are introduced into the organization. While it is possible to share elements of the style guide between different API styles, it is highly recommended to write a style guide for each API style at the start.

Over time, common recommendations such as naming conventions and reserved words may be shared between API style guides. However, most organizations find that there is significant deviation in standards and common practices across API styles. Remember that it is better to follow common practices for each API style rather than trying to unify all API styles into a single set of recommendations.

Finally, keep in mind that there is a cost to supporting each API style. Spend time to understand the needs for the new API style. Then determine if the needs outweigh the cost required to build and support yet another API style guide.

Conducting API Design Reviews

API design reviews seek to improve the design of APIs through constructive review and feedback. Implementing a healthy API design review process helps to capture insights, patterns, and lessons learned into a repeatable process, guiding organizations toward a more consistent design and a better developer experience.

API design reviews offer an organization a chance to:

■ Share knowledge of upcoming APIs

■ Incorporate design feedback before coding begins

■ Become an advocate for the many developers that will use the API once it is released

■ Offer a more consistent developer experience through consistently designed APIs

■ Catch missing or incorrect assumptions before code changes become more expensive or time is limited

Below are some tips and insights on conducting healthy API design reviews.

Start with a Documentation Review

API design reviews are not code reviews. API design reviewers are acting as an advocate for the developers that will consume the API. Therefore, it is important to start with the API documentation.

APIs exist for a variety of reasons, including data access, customer automation, system-to-system integration, marketplace creation, and workforce automation. An API's introduction should be clear about why it exists and how it might collaborate with other APIs to accomplish more complex workflows or outcomes.

Use the following as a review checklist for all areas of documentation:

■ API name: The name should be descriptive and make it easy to determine the scope of the API when first discovered

■ API description: The description should be comprehensive, starting with an overview of the API and including a list of use cases it solves

■ API operations: Each operation should offer a summary of what task, activity, or outcome it produces along with a description that includes detailed usage instructions. Ensure all input and output values are captured and properly described, including expected formats that could cause errors if violated

■ Example usage: Examples of API usage are often the most important, yet missing, element of an API's documentation. These examples do not need to be in a specific programming language (although that helps when trying to offer an API to a broad audience). Simple HTTP request/response examples, perhaps complemented with Postman collections, will go a long way.

■ Avoid internal references: Great documentation assumes that the reader has no idea about any of the internal systems or implementation choices behind-the-scenes. They just want to get something done and they want to find out if the API will help them achieve their goals.

Check for Standards and Design Consistency

One of the common challenges for many mid-to-large size organizations is API design consistency. It is easy to spot APIs that were independently designed by teams without any cross-org consistency applied. Commonly, this is associated with organizations that lack a design review process. Even with a review process in place, inconsistencies may creep in from time-to-time.

Part of the API design review should be to verify that the standards and design choices match any established style guides and standards. This may be performed by a combination of a manual review and through the use of an API linter such as Spectral.

Finally, look for opportunities to apply common design patterns consistently. Examples include CRUD, consistent use of pagination techniques, multi-part MIME for file uploads, etc. While these common patterns may be captured as part of the style guide, identifying deviations, and discussing them with the team will help to provide consistency whenever possible while making exceptions when appropriate.

Review Automated Test Coverage

While an API design review does focus on the design, reviewing test coverage is important as well. Including test coverage review ensures that the testing strategies for the API have been considered as part of the design. It also helps to ensure that the API’s operations can be used in combination to produce the desired outcomes identified during the align phase.

If the review is conducted early in the process, there may not be any specific code or test coverage in place. In this case, review test plans to surface missing or incorrect design assumptions. A good starting place is to review job stories, API profiles produced during modeling, and other artifacts. This will help surface any missing test plans and ensure the test coverage will be sufficient to verify operational functionality along with acceptance tests that will verify intended outcomes.

Add Try it Out Support

Nothing provides a better review of an API design than interacting with it. If code already exists for the API, go ahead, and try out the API. This will help to exercise the documentation, the API design, and the implementation.

If the team took a design first approach, little or no code exists yet. Mocking tools help to address this issue. Mocking tools are a great way to fill the gap and catch bad design decisions, or missing endpoints, sooner rather than later in the delivery process. These tools will often accept a definition in OpenAPI Specification, API Blueprint, and other description formats to produce a mock version of the API design. While the mock API won't be fully formed, it will provide a basic understanding of how the API will be used once completed and catch sub-optimal design decisions early.

Developing a Culture of Reuse

API consumers are an essential ingredient of any program. However, many organizations focus on strategy, objectives, and governance to create APIs without addressing the need to make adoption of APIs easy through discovery.

For most organizations, API documentation is an afterthought. This is unfortunate as it leads to serious consequences for API discovery and adoption, resulting in reduced reuse of valuable APIs. Organizations implementing effective API discovery subscribe to the following mantra: Discover digital capabilities when possible; build them when necessary.

API documentation is the first encounter most developers will have with an API, so providing great documentation is essential to helping them understand what the API offers, how to use it, and what to do when they are ready to start integrating. Documenting APIs is addressed in detail in Chapter 13.

Developers who are new to an API platform do not have an easy journey. In fact, development teams go through several phases as they evaluate and integrate the API, as shown in Figure 16.1.

To ensure developers can quickly get started with using the API, define a clear onboarding process. Set the expectations for the path from discovery to mapping and integrating their solution to the API. Don’t stop with winning developers with an API — stay in contact with them through newsletters or distribution lists. Announce new and upcoming improvements, success stories, and common use cases through consistent developer communication. Highlight the teams that are responsible for building and supporting APIs to demonstrate their commitment to meeting developers’ needs.

The Journey Has Only Begun

The focus of this book has been on principles of web API design that produce a repeatable, collaborative API design process that helps to deliver value using an outcome-based focus. These principles were:

■ Principle #1: APIs should never be designed in isolation. Collaborative API design is essential for a great API. (Chapter 2)

■ Principle #2: API design starts with an outcome-based focus. A focus on the outcome ensures the API delivers value to everyone. (Chapters 3-6)

■ Principle #3: Select the API design elements that matches the need. Trying to find the perfect API style is a fruitless endeavor. Instead, seek to understand and apply the API elements appropriate for the need, whether that is REST, GraphQL, gRPC, or an emerging style just entering the industry. (Chapters 7-12)

■ Principle #4: API documentation is the most important user interface for developers. Therefore, API documentation should be first class and not left as a last-minute task. (Chapter 13)

■ Principle #5: APIs are forever, so plan accordingly. Thoughtful API design combined with an evolutionary design approach makes APIs resilient to change. (Chapter 14)

The principles are the foundation for a four-phase process: Align, Define, Design, and Refine (ADDR). The ADDR process focuses on aligning stakeholders, defining the digital capabilities required, designing the API to produce the outcomes, and then refining the design based on feedback.

The process recognizes that an API should never be designed in isolation. It requires the collaboration of a variety of roles, including subject matter experts. By aligning those involved in API design on the outcomes first, the API remains focused on the value delivered. Along the way, stakeholders are aligned in their understanding using collaborative techniques such as EventStorming and API modeling prior to designing the API. The API is then designed and refined through feedback with those that will integrate the API into their solution.

While some may think that the journey has completed, this is only the beginning. The API design will now be delivered and managed. It will meet real world usage, perhaps even encountering new use cases never considered. The ADDR process will be used once again as the API grows and matures. For larger organizations, this API design lifecycle will be repeated for many new APIs, requiring the ADDR process to be scaled for use by multiple teams. The journey has only begun.