Milestones for the create stage

Every API begins life as a new creation, but you’ll need to decide when exactly that creation point happens. How do you define the beginning of an API product journey? Of course, all of this can happen organically. It’s perfectly fine to decentralize the creation decision and let individual teams create competitive API products. But you may still want to define some minimum level of diligence before API product work can begin.

For example, you could decide that every API product needs to have a strategic goal defined before design and develop work can commence. This would require some form of centralized decision distribution, probably in the form of centralized authorization. Or you could make a rule that anyone in the organization can invent an API product, but work can only begin if they find three other people willing to invest three months of effort.

How you define the creation milestone depends a lot on your context, but, it’s important to have a shared understanding of what it takes to kick off an API product lifecycle. That will help to avoid wasted investment in products that aren’t worth the effort.

Milestones for the publish stage

The milestones you define for the publish stage should identify when the API is ready for active usage. You’ll need to decide what kind of trigger constitutes being ready for real use. Here are some examples:

• The API has been promoted to a production environment.

• The API website has gone live.

• The API has been registered in the corporate registry.

• API availability has been announced by email.

In addition, you may want to define some measures that indicate if the API is actually being used. This will help you determine the potential impact of changes that you want to make early in the publish stage. For example, user registrations, API invocations, and documentation views may be helpful metrics.

Milestones for the realize stage

To build a KPI that identifies when you’ve reached this stage, you’ll need to have a very good idea of who you are building the API for. The audience for your API should be pretty easy to identify if you’ve been able to define your objectives with a reasonable level of clarity. That doesn’t mean that your target API user will necessarily be very specific user persona—lots of APIs are launched to be as flexible as possible with the goal of serving anyone and everyone. The important thing is to be certain about the type of user access that means you’ve realized the API.

At this point it’s also useful to measure the level of engagement that users have with your API. In fact, the primary goal for your API at this stage is to build engagement levels to the point that the API is being used legitimately—whatever that may mean in your case.

When an API enters the stage of realization, your job isn’t done. The best success will come from continuing to reap value from this product. That means having a set of measures that help you track progress and make product management decisions accordingly. The kinds of OKRs and KPIs we discussed earlier in the chapter have their greatest applicability for APIs in this stage.

Milestones for the maintain stage

The milestones for the maintain stage will be dependent on the milestones for the realize stage and are primarily trend-based. For example, if you already have a measure for user growth defined for the realize stage, a corresponding measure of growth over the last six months might help for maintenance. If growth stagnates or declines, this could be an indication that the API has entered into the maintain stage. You’ll need to define which measures are the key indicators, what the period should be, and what the threshold for stagnation is.

Milestones for the retire stage

Just like the other stages of API maturity, it is important for the API product team to define the milestones that would indicate the API is in the retire stage. These milestones might be performance-related (for example, the number of API messages processed over a timespan) or cost-related (for example, the estimated cost of improving an API to meet some future business objectives).

Google is famous for retiring products and projects that don’t meet specific measurable targets within a given amount of time. At Google, those targets could be active user numbers in the hundreds of thousands and the expectations of user growth can be quite aggressive. These types of measures make sense for a product strategy that seeks massive user growth, but wouldn’t be great for an internal user authentication API.

Milestones for the retire stage represent either a floor or ceiling threshold. For example, you may set a minimum number of requests that an API in the maintain stage must serve, or you could set a maximum cost level before the product enters the retire stage. The cost of retiring a product varies wildly based on the type of applications it supports and the scale of developer users. So, you’ll need to set these limits based on your API’s unique situational context.

Strategy

The create lifecycle stage is when the strategy needs to be developed in the first place. Once it’s established there will be very little real feedback about actual API product usage, since most of the work in this stage will be design and implementation effort. This lack of data about the strategy means that you should expect very little change to the strategy during this stage. One exception to this is when the cost of executing your strategy is too high. For example, you might find that it’s impractical to create a design and implementation that aligns well with your strategic goal. If that’s the case, you’ll need to make some strategic changes.

In the create stage, you:

• Design your initial strategy.

• Test it for design and implementation practicality.

• Update your goals and tactics based on feasibility.

Design

In Chapter 5 we described how API interface models become harder to change when the API gets actively used. This is why interface model design work is so important in the early stages of an API product’s lifecycle. If you can come up with the best design during an API’s create stage, you’ll have the greatest freedom to increment, improve, and innovate early.

A big challenge to designing in the create stage is that you’ll be making a lot of assumptions. You’ll be assuming that the design decisions you’ve made for the interface model are the ones that make sense for developers. You’ll also be assuming that your design will be practical to implement. Unfortunately, these types of assumptions are often wrong.

To get the best interface design this early in the life of the product you’ll end up having to perform some validation of your model. You’ll need to get feedback from the implementation team that the design you’ve come up with is feasible—ideally this validation includes the development of prototypes that can be called. You’ll also need some feedback from developers who represent your target audience.

In the create stage, you:

• Design the initial interface model.

• Test the design from a user perspective.

• Validate the implementability of the interface model.

Development

In the create stage, development work is focused on implementing an interface model to be published. As we described earlier, that work can also include prototype development for testing the design. The primary development goal in this first stage of life is to create an implementation that works and that provides all the functionality described in the interface model. But to really get long-term value from development, the implementation should also be designed to reduce the maintenance and changeability costs of the code, data, and infrastructure.

In the create stage you:

• Develop prototypes.

• Test the interface design from an implementation perspective.

• Develop an initial implementation of the API.

Testing

In the create stage you’ll need to test the interface design and initial implementation. This is your chance to expose usability problems and improve the design of the API early in its life. Like with all quality assurance, the cost of usability testing can vary. A high-investment version could involve lab-based usability tests, focus groups, surveys, and interviews. A low-investment version could be as simple as writing code for your API.

The right investment level will be determined by the value you’ll get from improving quality. If you are operating in a highly competitive API market and your audience has many product choices, investing in better usability quality might make sense. If you are designing the API only for yourself, you’ll probably perform only enough testing to validate your design assumptions. But in all cases, testing those design assumptions is necessary to avoid the rising cost of interface model change.

You’ll want to test the implementation too, but in the create stage the implementation quality isn’t as vital. The API hasn’t been published for use yet, so you can afford to defer an implementation testing investment to later. That doesn’t mean testing your code in the create stage is a bad thing. In fact, adopting practices like test-driven development will probably improve the quality of your implementation in the long run. The point here is just that it’s a decision you can make based on your own context.

In the create stage you:

• Define and execute a testing strategy for the interface model.

• Define a testing strategy for the implementation.

Security

When it comes to security work, the safe play is to invest in it heavily throughout the life of the API. The amount of actual diligence required will be dependent on the constraints imposed on you by your industry, government, and competitive marketplace, but it’s difficult to imagine a scenario where no security work is required at all. You will always need to do some work to protect yourself, your system, and your users.

A lot of this work needs to happen before the API is published. It’s no good to open up the doors to your API instances and only then consider how to keep things safe. That’s why we’ve identified the create stage as the most significant one for the pillar of API security. That might seem counterintuitive, but we believe that the security work you perform during this stage is the most significant and gives you the best chance of success. Security is most relevant for a live API instance, but the foundations for security are laid while it is first being designed and implemented.

During the create stage, your security work should be focused on applying security policies to your proposed design. If your industry or organization doesn’t have any defined requirements, you’ll need to come up with some yourself. At this stage it is important to make security a first-class concern within the interface design and implementation.

The implementation work in the create stage should include designing and building an appropriately secure infrastructure for your API. That includes access control functions as well as a design for handling overuse that might take your service away from legitimate users. No API is too small or unimportant enough to risk being vulnerable. In fact, great exploitation targets in any large system are those components that were deemed trivial and not worth the investment of a secure implementation.

In the create stage you:

• Define your security requirements.

• Validate the interface model against your security requirements.

• Define a strategy for securing the initial implementation and instances.

Design

Although most of the design work will happen in the create stage, interface design work remains important in the publish stage. That’s because this is your opportunity to improve the design of your interface based on actual usage. When you publish your API, you’ll find out if the assumptions you made about the design are correct. Some of that will come out during testing in the create stage, but you’ll learn a lot of new lessons once users get their hands on your API for real.

In truth, you’ll be making changes to the interface throughout its lifetime. Whenever you need to add a new feature, enhance an existing operation, or improve usability, you’ll be changing the interface model. But those changes will be easier to make during the create and publish stages. The publish stage is your last opportunity to make invasive design changes with a minimal amount of harm, or at least without impacting users who are delivering realized value.

In the publish stage you:

• Analyze the usability of the interface.

• Test design assumptions you made in the create stage.

• Improve the interface model based on your findings.

Development

If you change the interface, you’ll end up having to make changes to the implementation. But that’s not the interesting part of the development pillar in the publish stage. We are highlighting this pillar because the publish stage is the best time to optimize the implementation independent of the interface model. It’s your chance to improve the implementation such that it is more performant, and easier to change and scale.

You can certainly do this kind of work during the create stage, but the publish stage gives you the benefit of having real usage to base your optimization on. Unlike the interface model, you have the freedom to change the implementation in small, iterative steps. In this way, you can avoid having to do too much big design of the code up front. Instead, you can optimize it in small pieces as you learn more about what needs to be improved. In truth, you’ll continue to optimize your implementation throughout the life of the API, but the publish stage presents a great opportunity to do the most with the least risk.

In the publish stage you:

• Optimize the implementation for scalability and performance.

• Optimize the implementation for changeability.

• Make these optimizations based on observed usage.

Deployment

An API can’t be considered published if an instance hasn’t been deployed. So, deployment is a core pillar for the publish stage. At the very least you need to make sure an instance is available to users, but it’s a good idea to start building a deployment infrastructure that will support later growth. This is especially important if your API’s strategic goal involves increased usage. For example, reaching a revenue or innovation target will probably need a deployment architecture that can handle a lot of demand.

One aspect of deployment work is to develop a release pipeline that will allow you to make changes to the API (recall that it’s important to achieve velocity for your API changes). The work of designing and constructing this pipeline should ideally start during the create stage of the product, but the publish stage is when it becomes more urgent to get one in place.

Another aspect of deployment is the work of operationalizing your API instances. This means building and maintaining a system that will address scale, availability, and changeability requirements for your product. A good operations system will keep your API available and performant even as the demand on system resources grows. Keeping your API instances in good health is an essential part of building a good developer experience. An API that is frequently unavailable or unreasonably slow will have trouble moving to the realize stage.

In the publish stage you:

• Deploy the API instance.

• Focus on making the API available.

• Plan and design your deployment for future demand.

Documentation

You’ll need to perform documentation work throughout the lifecycle of your API, but the documentation pillar becomes particularly important during the publish and realize stages of the API product lifecycle. During the publish stage you’ll be trying to increase the realized value of the API by attracting the right kind of usage. This is your chance to experiment with the documentation design and come up with something that helps you get the usage you want.

That means you can start with a low level of documentation maturity and keep building it up as you learn more about your API’s usage. For example, you might start by offering only a technical reference, but add tutorials and examples based on observed usage. In particular, this allows you to focus the documentation on the trouble spots or learning gaps of your API. You can find those by investing in user testing during the create stage, or in the publish stage from the questions that your users will ask.

In the publish stage you:

• Publish documentation.

• Improve documentation based on actual usage.

Monitoring

Getting product feedback is most important in the publish and realize stages of the API lifecycle. In the publish stage you need good measurements to determine if you’ve hit your realization milestone. In the realize stage, you’ll need data to ensure that your API is still trending upwards in terms of demand and realized value. Monitoring is useful throughout the entire product lifecycle, but it’s essential for these particular stages. You’ll usually use the same metrics in both the publish and realize stages, so if you invest in good monitoring here, you can reuse that solution later.

In the publish stage you:

• Design and implement strategic measures for your API.

• Design and implement system monitoring for your API.

• Build a monitoring system that can be used during realization.

Discovery

Discovery is the most situationally dependent of our ten pillars. The work of discovery is the effort you expend to promote the API product, engage with developers, and generally increase the traction your API has with your target audience. If you are developing an API for your own team, discovery can be as simple as sending an email. If you are building an API for a large enterprise, discovery could mean following an intake and registration process for new services. If you are building an API for the general public, it could mean hiring a team of ten people to build and implement a marketing strategy. That’s quite a wide spectrum of effort and investment.

But in all of these cases, regardless of the effort expended, the value of discovery is highest during the publish stage of the API’s life. This is when you’ll want to maximize engagement with your API, because you have instances available to use and the right usage can help you generate realized value from your product. But as we said earlier, how you do this discovery and how much you invest is highly dependent on your context.

In the publish stage you:

• Invest in marketing, engagement, and findability for the API.

Deployment

When the value of your API is realized, it’s imperative that you keep the system available and running for your users. That means that your deployment architecture becomes very important. While you will have performed your initial deployment design during the publish stage, in the realize stage you’ll focus on maintaining and improving it. That means taking the necessary steps to keep your service running even as the demand profile changes in unexpected ways. Making these kinds of changes may even require you to redesign the implementation. That’s perfectly fine as long as you can protect your high-value users from being negatively impacted.

In the realize stage you:

• Make sure that the API’s instances remain available.

• Continually improve and optimize the deployment architecture.

• Improve the implementation as necessary.

Documentation

The realize stage is your opportunity to continue to improve the developer experience of your product. In particular that means improving the documentation and learning experience. While it becomes more difficult to change the interface model at this point, changing the documentation is much less impactful. Humans are much better at adapting to change than software, so you have some freedom in experimenting with new formats, styles, tools, and presentation. The goal here is to continue to drive realized usage by reducing the learning gap for new users.

In the realize stage you:

• Continue to improve the documentation.

• Experiment with additional supporting assets (e.g., API explorers, client libraries, books, and videos).

• Drive new usage by reducing the learning gap.

Testing

In the realize stage, testing work prevents changes to any part of the API from having a negative impact on users. At this stage, usage of your API is directly contributing to the value of your product. Changes will be necessary, but you need to mitigate the risk that changes will cause undesirable effects. The level of investment you make in this type of testing work should be based on the impact of things going wrong.

Ideally, the kinds of tests you run in the realize stage already should have been created in the publish and create stages of the API lifestyle. But as your API approaches and enters the realize stage, your testing strategy should be evaluated to make sure it is giving you the best levels of risk mitigation. As the API matures into maintenance and eventually retirement, the demand on testing will decrease. During these stages you should be able to leverage the assets you’ve already created.

In the realize stage you:

• Implement a testing strategy for interface, implementation, and instance changes.

• Continually improve your testing solution.

• Build a testing solution that can be used in future stages.

Discovery

Discovery in the realize stage is broadly similar to the discovery work from the publish stage. The only difference is that the discovery work here can be more precise. You’ll have a better idea of which user communities provide the most value, so you can invest more in fostering those ones.

In the realize stage you:

• Continue to invest in API marketability, engagement, and findability.

• Invest more in high-value user communities.

Change management

The heart of the API product lifecycle is the evolving impact of changes to the API. In fact, we’ve been describing change management throughout this section, for each of the other pillars of the API product. But in general, when it comes to change management as a work pillar itself, it becomes most important during the realize stage of a product’s life.

In Chapter 5 we described the four types of changes that you’ll need to manage with an API product: changes to the interface model, implementation, instances, and supporting assets. Within each pillar, you’ll find yourself making changes to many of these API parts, often at the same time. All these changes need to be managed to reduce their impact, but this impact reduction is most important when you have active, realized usage. This is when a good change management system and versioning strategy will provide the most value.

In the realize stage you:

• Design and implement a change management system.

• Carefully communicate changes to users, maintainers, and sponsors.

• Support change activities with a goal of minimizing impact to realized value.

Monitoring

If your API is in a state of maintenance, your only objective is to keep the status quo. That means less emphasis on design, development, or change and more emphasis on support and availability. You may not need to make monitoring improvements at this point, since a lot of that work will have taken place during the publish and realize stages. But it’s still the most important pillar in the maintain stage, so you’ll need to invest some time and energy to make sure you are getting the right kind of system- and product-level data.

One objective is to have a system that lets you know when something out of the ordinary happens. That will be an indication that you have some work to do. Another goal of monitoring in the maintain stage is to keep an eye on the value that your API is providing. When it drops too low, it may be time for the API to be retired.

In the maintain stage you:

• Ensure that the monitoring system is operational.

• Identify patterns that will require special care.

• Observe metrics that could trigger a retirement decision.

Strategy

When it’s time to retire your API, you’ll need to address a special set of strategy issues. How will existing users be supported, compensated, or placated? Is there a new API that users should be migrated to? What is the timeline and set of steps that will need to be in place for the API to be retired? How will the impending retirement be communicated to the user base? Regardless of the scale, context, and constraints of your API, you’ll need to form some type of retirement strategy, even if it’s a minimal, informal one.

That means forming new goals, new tactics, and a new set of actions. The original goal of your API that you have set in the create stage is no longer your target. Instead, you need a goal that fits the retirement of your product. For example, you may have a goal to minimize the number of users you’ll lose if you want them to migrate to a new API. Or your goal might be to eliminate the cost of supporting the API as soon as possible. These two very different goals will each require a tactical plan and set of actions to enable them.

In the retire stage you:

• Define a retirement (or transition) strategy.

• Identify a new goal, tactical plan, and set of actions.

• Measure progress toward this retirement goal.

Change management

Managing change in the retire stage means managing the impact of retiring the product. This isn’t the time to introduce enhancements or improvements to the API, so the focus here isn’t on versioning or managing a big rollout. Instead, the work here involves assessing the impact to your users, brand, and organization of an impending deprecation and managing that change effectively. This work should align with your retirement strategy.

In the retire stage you:

• Assess the impact of retiring your API.

• Design and implement a plan of communication and deprecation.

• Manage implementation and instance changes to support that deprecation.