API Lifecycle: Design Stage (Part 2 of 4)
This series covers an overview of the 4 API lifecycle stages with digitalML’s ignite scaling platform. It’s an enterprise platform with tons of features, but here we are running through the highlights. If you haven’t yet, we encourage you to check out last week’s post on The Plan Stage.
Different by Design
As we discussed last week, the digitalML API Product Lifecycle differs from many other API lifecycles you’ll find out there. This is all thanks to our show’s star: The Design Phase.
For many API lifecycles, API Design is either thrown in with the Plan stage, an afterthought in development, or left out of the lifecycle altogether. Perhaps this line of thinking comes from the afterglow of the SOA days, which taught us we can’t spend too much time on comprehensive business alignment, consistence and governance — we have to go fast. But we think you can have your cake and eat it too. That you don’t have to give up control for speed.
Speed with Control
We believe in the power of an API portfolio with standardized design artifacts that drive automation. (ignite automatically generates the interface and code for any language — we’ll cover how this makes maintenance so much easier in our article on the Build phase). Our platform enables your teams to design microservices in the language of the business and with consistent resources (the right way), so that you can avoid snags down the road and get reuse.
Imagine a fluid lifecycle: no bottlenecks, built-in change management, governance, impact analysis, and traceability. A lifecycle where iterative changes are made early in the design phase, where they’re cheaper. Where interfaces are autogenerated from the details captured in the specification, developers are able to focus on big brain activity, and business capability coverage continues to grow. Well, we’re here to tell you, that’s not just your imagination — it’s a real state.
The two schools of API Building…
In the API building community, there exist two schools of thought: design-first and code-first. (Check out our post on how these two should figure in your API Strategy.) Traditionally, IT has built according to what the system owner wants to build. But with the increasing ability to receive feedback from customers — both, internal and external — times have changed. Lately we are collecting copious amounts of data on customer feedback, in real-time. So it makes sense that, especially for big data collectors, the code-first process is inverting.
…and why design-first is important.
God’s Treehouse: built by “divine inspiration.” No plan, no bueprint, no building code. A wonder to behold, 14 years to build; Shut down in 2012 by the local Fire Marshall.
It’s all about alignment. When you build without a plan, you build at the risk of your users. The fact is, if you’re not building for the user, you’re building for the owner, or more often than not, the builders, divinely inspired as they may be. (Not to draw comparisons). In certain situations, the code-first approach is a perfectly acceptable methodology. In enterprise architecture, it rarely is. We believe that if you have 2,000+ resource capabilities across 20+ domains, decoupling your assets into modularized building blocks is the only way to be flexible… ahem, digital.
Common Microservice Building Blocks
Think, school of fish vs. submarine: who’s better at a 180? Hands down, the school can turn around quicker; if they’re coordinated and following a plan. Such is the core ideology behind microservices architecture.
You already exposed your resource capabilities and made them into building blocks while you were building out your API portfolio — another reason the microservices model is such an asset. So now, instead of creating a brand new API from scratch, ignite allows you to build with these Business Capability APIs, which are decoupled and ready to plug in, in contrast to code-first point-to-point projects.
The Benefit of Designing APIs with a Data/Taxonomy Model
Rather than use a spreadsheet to capture requirements/specifications on the data flow, consuming providing systems, and definitions, and then pass on to a developer to use as a reference when he or she creates the API (fingers crossed it’s built in the language of the business), ignite has the design lifecycle, where you can use your resources to define the specs to your solution, and then generate the interface and code in any language (not just java or c#, but also transformation code, as well as service handler code) based on whichever operating platform you’re using.
This provides a huge value: No asking a developer to define a resource (“How do we define a ‘customer’?”) + no duplication (APIs are expensive!) + no handcoding in the Swagger editor = quicker time-to-market.
Important note: The ignite API Product lifecycle is NOT a waterfall process! Hence the belts between the gears. In fact, the design-first approach is a much more agile methodology than code-first, in that it encourages end-user input, version control for change management, and quick restructuring through technology-agnostic code automation.
The Deep-Dive View
The 5 key steps to Designing an API with ignite are 1. capture Summary Info, 2. define Resources used, 3. define Resource Methods used, 4. Review and 5. Publish.
In summary info, you will define the name, description, what the service supports (business capability, core service, platform service (middleware), etc), and what level of your architecture it’s going to operate in, what it’s exposed to, a brief description of the service, and a version number. Here you can choose how you would like the view to be displayed, from a top-down, or bottom-up perspective.
Next, you’ll pick the resource data to manage. This is anything you have defined in your canonical/resource models — the great thing here is, you only have to define them once (much happy, very consistency). Then choose the resource methods your API supports, review, click generate — and voila. Now you have a usable JSON Swagger interface, code, documentation, test conditions. Everything is aligned to your architecture standards, ready for implementation, and deployable to run.
Mapping and Standardized Design Artifacts
Why is our code automation feature such a client favorite? Because time is money. What used to take one month with ignite takes a matter of hours. Two days at the very most, and that’s only in extensive documentation cases. This is all possible thanks to mapping. As we mentioned, mapping allows your team to avoid handcoding, AKA months lost, and massive headaches — particularly true in the insurance and banking industries, where many of our customers are trying to consolidate 2,000–3,000 services down to 400.
With ignite, when it comes time to use your business capabilities, they’re already integrated into your backend applications. So after you have that mapping done once, you’ll have it for eternity. And you’ll have traceability from implementation back to the business and stakeholder systems — meaning: core system replacements are done in a fraction of the time; auditing and regulation reporting are made easy; and IT modernization parallels digital transformation.