API DesignAPI ManagementAPI Product DesignAPI Product StrategyBusiness Capability APIsIT Modernization

How “Code-First” And “Design-First” Should Figure In Your API Strategy

Developers building mobile apps sometimes ask “why can’t I just use a code-first approach to defining my data?” They argue that Microsoft’s Entity Framework, enunciate, or Breeze makes their lives easier, fits well with their Agile delivery process, and reduces the whole issue of data definition to an easy one they understand, in defining their own language objects (Java, C#, Javascript, etc.). And if all you ever need is an object-relational mapping API to a siloed database for that app, then code-first works just fine. Database vendors love this approach because it sustains the proliferation of redundant data, and of database license revenue.

But what if your real objective with APIs is to join the API Economy, for those APIs to be the digital “face” of your firm? This makes the design of those APIs paramount, and means you should use a design-first approach to defining your APIs (a.k.a. “contract-first” or “interface-first”). Your API portfolio is your digital business, and you should no more leave the design of your digital business to a random collection of development projects, than a bank would leave the design of its branches to the people who work in them.

The keyword to remember is interoperability. If an API will only ever matter to the team that’s building it, and will only ever be the slave to their app, then code-first is OK. But if an API is the boundary between one team that provides the API, and multiple teams that will consume it, then:

  • These APIs play a much more critical part in delivering the capabilities of your digital business – and you must govern their design to ensure you achieve interoperability between API consumers and providers.
  • These API designs are crucial to your ability to achieve objectives such as delivering OmniChannel experiences to your customers. This is the only way you can deliver the consistent information, consistent outcomes, and friction-free commerce your customers expect from a digital firm.
  • Humans must understand your APIs. This requirement plays a bigger role in your API design approach than any other constraint you face. It’s highly unlikely that an API that mirrors the object graph of a single application will pass this test, except to the programmers who wrote that app.

One of the things developers like about code-first is automation, but the good news is that you can leverage automation for a design-first approach, too, through using tools like ignite and Swagger, together, to automate your API design lifecycle. Swagger is the most widely adopted design-first environment for APIs, which is why ignite integrates it into its API design approach.

Design-First Doesn’t Mean Waterfall

To an Agile developer, design-first can sound suspiciously like the bad old days of waterfall development, but that’s not really what it means. It means that the API design becomes a first-class citizen along with other work on the backlog. Teams building and using APIs should collaborate and iterate together. That’s why digitalML advocates publishing your API design to developers at the earliest possible stage, when it’s little more than a twinkle in the eye of a business analyst or architect. This is the best way to get rapid feedback from developers who need to consume the API to build their apps, enabling you to refine your API design and rapidly iterate through various design ideas before you build it.

SwaggerUI’s sandbox functionality helps enable this way of working, letting developers play with the API before it even exists. Ignite’s latest enhancements to Swagger integration speed this process still further, via simple forms and wizards that accelerate the design process. This is the key to pragmatic parallel development, with teams that provide APIs working in parallel with the teams that consume those APIs, so everyone reaches the endpoint more quickly. This is also helpful in increasing reuse, as you avoid proliferating APIs that are overly specific to one app – “API chaos.”

Yes Virginia, Your Canonical Is Still Important

As we observed in this blog post, you will likely have a wide range of API types in your portfolio, but if one mission of your API portfolio is to deliver an interoperable interface to your digital business, one that can deliver OmniChannel and other similar goals, then you should take advantage of ignite’s capability to ease consumption of canonical elements and attributes in your design. This is a crucial element of achieving interoperability, even when you also have APIs that are more specific to particular apps and touchpoints.

For those APIs for which code-first is a reasonable fit, because they are internal to one project, consider a hybrid approach: capture the design of those APIs (code-first tools can generate Swagger, too) and publish them alongside your other APIs that you know need to be reusable. As those code-first designs evolve, examine them for new data you should harvest and add to your canonical. Sometimes a piece of data that appears first in one app context will later propagate and become important to other applications.

It’s only by managing your entire API portfolio that you can achieve your API goals in the most efficient and effective way. The different types of APIs across your portfolio justify varying degrees of governance, but all your APIs should be held to the same standards of transparency, to ensure all APIs are subjected to the kind of peer review that brings the best outcomes. Ignite can help you balance fast delivery with good governance in a way that development teams can love.


Related Articles