API DesignAPI DeveloperAPI Product LifecycleAPI Product ManagementAPI Product ManagerCitizen DeveloperDeveloper EvangelistDigital Product ManagerIT Modernization

Why API Design, Why Now?

Why API design?

No matter your company’s size, you’ve likely tapped into the usefulness of the simplified calls of APIs and microservices that bring your business offerings to surface.

If you’re a smaller company specializing in only a handful of digital offerings, handcoding your APIs point-to-point makes perfect sense. You only have so many to manage, and you’re likely using a lot of third-party APIs to carry out many of your business processes — hey, that’s the beauty of the API economy — in today’s world, your small business can be entirely built on OPA’s (Other People’s APIs).

BUT. For large organizations doing digital business (ahem… every enterprise), your hands are full.

It’s been a whirlwind to build out the many touchpoints of every digital marketplace you’re expected to have a brand presence. And it’s been an F5 Twister to manage the growing number of microservices and APIs that are starting to crop up for those and internal processes — much less, to update legacy systems (again).

Why API design, why now?

As all of digital business increasingly hinges on APIs, the question comes to scale.


Digital business at the enterprise level requires APIs at scale.

Most enterprises have dipped their toes into the API economy by now, and they understand the real value of API implementation. They all have API strategies in place, and they’re all at various stages of API maturity; whether they’re focused on internal APIs, or they’ve built an open API platform to garner new partnerships and innovative applications. If they’re further along, perhaps they’re migrating from monolith to microservices architecture. (Check back soon to calculate your own API Maturity Score — we have a worksheet in the making.)

While a complete rip-and-replace may not be on the table for your company quite yet, you’re likely wrapping more and more of your mainframe systems into flexible REST APIs.

Meanwhile, the backdrop of constant change continues to shift at an alarming rate — changing roles, changing lifecycle, changing architecture — today’s technologies may very well be obsolete tomorrow. So how to know where to place the focus?

On the one thing that doesn’t change — the one thing that is in fact, prized for its dependability: your business’s best.


Technology changes; your business’s best doesn’t have to.

Technology is going to change — there will inevitably always be new coding languages, new services, new methodologies to get used to. New marketplaces, new platforms. The IoT promises to bring challenges in the form of integration with new devices — and all of these changes are occurring at an accelerating pace in an increasingly globalized world.

Accelerating Change in Technology
Source: Seeking Alpha

What changes far less often is your business offerings.

With good design, hooking up to constantly changing endpoints can be the easy part — by automating the build with code generation, you can keep your focus on greater things; what you’ve spent decades building. Your database, systems, portfolio.

As you make the pivot to digitize your greatest assets, it is critical to place the focus on the design rather than the application. Get the design right, and you can adapt to whatever changes come your way. Because change is coming, and of that, we can be sure.


API design smooths changes in the SDLC.

A big change, as we discussed a few weeks back, is taking place in the development part of the software development lifecycle.

As new technology and methodology like containers and CI/CD are rapidly changing the developer’s job, and as that lifecycle speeds up, the question of scale places increasing eminence on design in the lifecycle. (A wonderful podcast on this subject was published just earlier this week over at a16z.) The emphasis changes from manual editor-based design and development to a powerful design-led development platform.

For customers of digitalML, each API or Microservice has its own design managed within ignite — globally visible and accessible, and able to be reused, or extended at the needed level of granularity. These designs hold a comprehensive set of information about that API in a format abstracted from any specific implementation, technology, or code type (Fig A. above).

When complete, the design can leverage a set of templates in ignite to automatically generate pretty much all of the artifacts needed directly into your SCM CI/CD process. These artifacts include; Proxy configuration setting, the interface, orchestration code, transformations, test conditions and documentation.

This allows you to keep the gateway / proxy configuration separate but linked to your execution code of choice, so you can reuse an API design for multiple endpoints.


What the design-first lifecycle does for your service catalog.

The design-led approach has many benefits for expanding your API and Microservice catalog.

It means your catalog is well-thought out and constantly growing and feeding back into itself — more coverage means quicker build means more coverage — which also brings more alignment. If you’re doing this right, your catalog is starting to match the business requirements across all business functions, rather than simply holding a repository of new technical debt with lots of duplications.

What the ignite platform does well, to that end, is marry that catalog to lifecycle, for an integrated, seamless build across every stage of the lifecycle.

By automating this design-to-build process, ignite bakes in governance and speed, as well as opens up API development and extension to less-technical “citizen developers.” (More on this in our upcoming API Channel blog.)

But getting faster to a great catalogue is not the end of the story. You now have all your APIs and Microservices designs held in a technology and code-agnostic format, which means it is simple to evolve those designs over their lifecycle. ignite’s analytics are made to help you test and choose new technologies and coding standards.

So implementing changes is now a simple matter of switching the templates used to generate the artifacts into the SCM CI/CD process.

Meaning, changes in technology and methodology are now an opportunity — not a bottleneck.

What your API design artifacts look like in action.

So what does great design actually look like for your digitized business assets? Picture prepackaged building blocks for each business capability you provide.

When it comes time to build, this means development is assembling pieces that already check the boxes, rather than building from scratch, or worse — adding more technical debt to the monolith.

ignite allows developers to wrap these building blocks together with the proper mappings, parameter, policies, etc. to create an API Product Design (see Fig. A below) from which any multitude of API Products can be generated for your many endpoints or consumers.

So all of the work that goes into that one design can be reused for hundreds… thousands of endpoints. This is what we mean by scale — APIs designed so well that they can be consumed as is.

Business Capability APIs are an important part of your API Product Designs
Fig A. From one API design, multiple API products can be generated. Original source: Forrester API Design & Documentation Report


Further Reading: Forrester’s API Design Report

Whether you are a customer or not, we encourage you to look further into the benefits of a design-first lifecycle. Last week, Forrester released their annual API Design & Documentation Report. The report is worth a read, especially for those who work in complex organizations with ambitious digital and modernization initiatives.

API design is the fulcrum that determines how much value an API strategy creates. Forrester, API Design & Documentation Report


Key Takeaways from the report (Download below):

1. Emphasize business APIs and portfolio management

  • Business APIs provide direct access to an organization’s business capabilities without tying API users to specific applications
  • A portfolio provides a coherent, consistent set of APIs (and services, events, messages, information models) that are available internally (or externally if you choose) rather than haphazardly building to the point needs of isolated projects

2. Establish product management disciple for business capability APIs and API Products

  • API providers should offer, and consumers will bundle, multiple APIs into an API Product. An API Product may combine whole APIs, or only individual operations from multiple APIs
  • Manage API Products as actual products – like products, APIs have providers and consumers so treat APIs like products with communities that care about and want input into product futures

3. Agile plus architecture while identifying centers of gravity 

  • Business led API design doesn’t happen in isolation, but to allow for collaboration you need visibility and a bidirectional heartbeat and prioritization between delivering innovation and unlocking capabilities
  • There will be multiple centers of gravity across roles, initiatives and lines of business with different cadences and priorities – collaboration, agility and architecture create the right balance between freedom/speed and the consistency that ensures sustainable business agility

4. Set a lifecycle for API design and documentation within the broader API lifecycle

  • The discipline of API Portfolio management provides context for designing individual APIs so that over a surprisingly brief amount of time, an organization can build a portfolio that provides full coverage of their business capabilities exposed through APIs
  • This becomes easy and fast when you bake in API documentation, domain-driven design, consistency and governance into the process, so it’s part of the (early & often) effort instead of a bottleneck

5. Use DevOps and continuous delivery to drive automation across lifecycles

  • API design doesn’t end once an API is pushed to run, you need a way of knowing the impact of making a change to an API will have everywhere it is being used
  • End to end version control and lineage reduce complications as APIs evolve

6. Great API design and documentation are both critical to world-class APIs

  • But it’s only part of the API Product/API Lifecycle and your API/microservice/event/digital transformation strategy.

Download report here:



Related Articles