You’ve put your time into great API designs. You chose what was best for the business, checked all of the boxes, set your company for better alignment, visibility, governance, clean reporting — and yet the designs never seem to catch on.
They’re never fully executed, and it’s no wonder, with the amount of spreadsheets, emails, mappings, Swagger/OpenAPI, legacy systems, etc. your teams are trying to keep up with. Add to the mix the geographical and language barriers of a global company, and duplication from region-to-region seems unavoidable.
But it can’t go on. Digital business presents too much opportunity to justify poor design that won’t build for reuse and provide end-to-end, real-time reporting. There’s no excuse for anything short of operational excellence when the right tooling and architecture exists today. If the incumbents are ever to compete at the global scale, they have to get a grip on their digital assets. The only way is through a design-first API Product Management strategy.
In our experience, the results always evangelize the method: The teams operating on the right design-first strategy bring in the fastest turnaround with the best designs, cleanest data, and swiftest governance. Other teams start to notice, the strategy gets C-level buy-in. And enterprise rollout naturally comes next.
In this post, we’ve asked one of our Enterprise Account Directors, Dan Kies to share a few working tactics that have proven to give enterprise API designers global adoption. Read on for a number of tried-and-true tactics API designers can employ to ensure their designs spread like fire.
1. Design for success
If you want to have a successful API, the first question you want to ask is how will we measure success? Is it the number of consumers, the number of hits, the availability, the revenue it generates? All of these approaches are relevant (and actual examples) in the API Product space.
While we cannot tell you what success is for your API, we can tell you that by setting expectations with stakeholders whose goals will be aligned to your APIs can be a great start. Without that alignment you’ll start to see cracks at the seams when anyone asks what the overall goals are of the API Product.
One customer, a large retailer, had an API Product reaching over 1,000 transactions per second, but the business was not happy with the overall API product. The business was aligned to the amount of revenue being generated through the API and the technical team was interested in ramping up for higher throughput – they assumed this would reach the business goal.
The problem was, they had two different measurements of success. By aligning the API Product success to both, the technical (TPS) and the business (revenue), the team became much more successful. This is a good example of what happens if you…
2. Know your consumers.
When designing any product it is paramount to understand who will be consuming the product, what their expectations are, what their previous experiences of similar products are, and what their product usage is. Designing an API is no different, you could be designing the API for a 3rd party business partner, a mobile client, an in-house consumer, or for discovery in a developer portal. What are the consumers’ expectations? Do they expect to be a heavy user with thousands of transactions per minute for eCommerce searches, are they using the API once a day to pre-populate a catalog, is this a financial transaction that needs to be auditable on a PCI network?
These factors can have a major influence in the API design approach and successful API Products offer high amounts of API interaction, from API Analytics, to advertising new features with Web Conferences, email notifications, publishing to Service Catalogs, and Friday pizza parties – yes, pizza will bring your consumers to talk about your APIs Design. It’s always a good move to…
3. Get the consumers involved early and often.
MVPs, requirements sessions, demos, hackathons, email campaigns – your API consumers have business changes coming their way every sprint just like you do and your current API design becomes legacy as soon as it is in production so how do you anticipate those changes?
You plan for it. The next version, the next sprint, the next payload samples, the message model changes. Your usage is skyrocketing and you and your planner have to make the decisions based on business priority, consumer needs, bugs, gaps, and ever-changing business direction. Because of this high rate of change…
4. Plan a versioning strategy.
The days of quarterly releases of APIs or large system releases are being gutted in favor of monthly -> weekly -> daily releases that support a positive continuous integration and delivery strategy. APIs are very well-suited for this task; we saw a customer recently implement a strategy that looks like this:
- Quick plan for a new API Version
- Identify the existing API
- Create the new API version
- Do an automated gap analysis on
- The payload
- The interface
- The design changes
- The affected consumers
- The affected SLAs
- Publish and launch
What’s your versioning strategy or challenge? (click here to tell us)
With your versioning strategy, you should be clear and transparent in your approach by…
5. Publish your APIs to an API or Service Catalog – and give Stakeholders Access!
Put into place a publishing strategy for your API designs and products. Where does the developer go for the interfaces? Where does the digital business team go when they want to see what’s out there to innovate? Where does a product team member go to see SLAs and analytics? Where does the sales team go when they want to see how much a customer is using a product?
The answer is obvious, this is what a Service Catalog is for. A Service Catalog puts into place a system of record that holds the information all your different stakeholders need to quickly get what they need. The Service Catalog needs to be easy to use and find API and Service information that is relevant to the role or stakeholder involved. A developer will be looking for different capabilities than a digital business user here so be sure to allow for role differentiation accordingly.
In addition to the Service Catalog, you may need to distribute API Interfaces, code examples, payload samples, and metadata directly to Developer Portals, SCM, and Runtime API systems. Once you establish a strong relationship with your consumers, make their job as easy as possible to complete and they will love your designs for it.
Your Service Catalog can be aligned across your stakeholders and domains more easily if you…
6. Apply Domain-Driven Design Principles to your API Design.
A. Use a message model
Message models have been around since the early days of SOA and they have found their place in the API world by making it easier to create consistent experiences for consumers while speeding up delivery. API Programs that use message models successfully can more quickly onboard new developers, products, and API consumers.
B. Align APIs to business capabilities (domains)
Business capabilities are the maps that break down “what the company does” into a level of granularity that can be quickly understood by stakeholders. An example could be “Claim” for an Insurance company, “Patient” for healthcare, or “Account” in the financial world. By aligning the APIs to the categories of your organization your APIs will benefit by becoming more loosely coupled to the consumers and more reusable and consistent.
C. Don’t expose your complexity to your consumers
If you are involved in a large and complex IT organization you probably have a name for what you call the spaghetti, the hairball, the skeletons in the closet, or the “technical debt”. As a practitioner of design, it is your responsibility to make sure that the consumer is not impacted by the hairball. That means that your API creates a façade that everything behind the scenes runs like a well-oiled machine.
D. Use the “language of the business” as much as possible
The “language of the business” can be very complicated to explain and it can often be misinterpreted. Recently in a customer discussion the term “Policy Year Policy Abatement Coverage” came up. Without a background in Insurance you probably wouldn’t know that this represents a certain view of premium allocated to the policy year (the year the current policy starts) and how the policy manages mixed “abatement” coverage for unexpected risk. Whew. You don’t want to have to define a complicated term like that twice, so let the business do it in a glossary, or in your API Design and have that carried forward to all of the consumers.
One Last Thought…
A question that comes up often is “How many microservices” will my domain or sub-domain need? It’s a good question, the more you break down the domain into microservices you should start to de-duplicate redundancies and create much simpler core or capability APIs that represent these. Although the underlying microservice implementation might be a legacy system or a new system based on docker architecture – heck it might even be a third-party outsourced microservice, you should expect the number of supported microservices to be expanding over the next few years until a plateau has been reached. Which begs the next question, how many orchestrations I need – but let’s save that topic for another day.
Have questions? Want to learn more? Book a call today.