API ManagementAPI Product DesignAPI Product Lifecycle

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 Stage.

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 Catalog 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.

what is design first

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 Catalog — 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 Building Blocks, which are decoupled and ready to plug in, in contrast to code-first point-to-point projects.

The Benefit of Designing APIs with a Domain-Based Information 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 Information, 2. Classification, 3. define Model Objects used, 4. Pick the Actions  your API supports, and 5. Secure your API and 6. Review and generate your design.

1. In Summary Information, you will define the name, description, and a brief description of the service. You’ll also add your Base URI here.

2. Next, you’ll describe the Classification, where you’ll name what type of API it is (Facade Business Capability API, Internal Application Integration API, OpenWeb or B2B API, Canonical Message, or a Core Business Capability API) and then you can specificy what its business capability is, so that you identify there are a number of capabilities attached o the API you’ve created. So when you navigate your catalog you see the API in these classifications, it makes it easier to find things.

3. When you identify your API Model Objects you will capture the Resource Name, and the model object for said resource.

4. Next, when you Specifiy Which Actions or capabilities the API should have, you’ll simply select the resource methods that apply.

5. Then you’ll select the correct User Authentication required by your organization (this can be automatically applied).

6. Lastly, you’ll Review what you’ve just made and make sure everything looks right, and… voila. That’s it — you’re done. You can configure your system to automatically deploy to run in your sandbox environment, or not. Up to you.

api security with ignite by digitalml

The great thing here is, you only have to define your specification once, review and ship, and you’re left with a usable JSON Swagger interface, code, documentation, test conditions. Everything is aligned to your architecture standards, ready for implementation, and deployable to run.

Design: the 2nd phase of the API lifecycle

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.

For more information, please check out our Lifecycle pages, which cover the 4 separate stages more fully. If you’d like to get started with ignite today, please book a consultation.


Related Articles