Adding 3 new factors:

• What is API First

API-First architecture/strategy is a new architecture approach the shift the mindset of software development for APIs to consider APIs as independent product,  with different journeys in order to achieve business objectives, independent from the UX journey that may mislead/abuse the API architecture and design.

You can just imagine it if you just think that your final product is the APIs, and you will commercialize it alone, without UX.

It means, you have API as a product, so you have:

1. Product manager

2. Product Roadmap

3. And product lifecycle

As example, the target persona of your product (APIs) which will use your product, like mobile app, web app, and smart watch.

So, We are starting with the API, not the application.

So, It's about "How will you image the solution upon the API first, not how to build the API upon the design first solution".

Why?

• Async Development

• Reduce development Cost

• Reduce time-to-market

Principles

Same like software engineering lifecycle, passing all journeys as the opposite diagram mentioning, considering that your product is APIs, including its documentation and journeys.

As a pre-requisites, We should build the culture, which implies the following principles:

• Your API is a product

• Foundational design, not ad hoc retrofit

• Team collaboration and impact

• API-first supports microservices

• The API contract

Ten Process Steps

Step 1: Create API Micro-Service architecture according to DDD, which each object has the following attributes:

• Who Am I?  I'm Employee Class

• What I know? I know my code, name, birthdate, current salary, current role.

• What I do?  I can Create employee, delete employee, activate employee, deactivate employee, update employee, and block employee, and unblock employee

• What is my state? like : blocked employee, Unblocked employee, Active employee and Inactive employee

Step 2: Determine key domains

Step 3: Determine each domain lifecycle

Step 4: Model your architecture domains

Step 5: Model your architecture sequence diagrams

Step 6: Model your architecture state-chart diagrams

Step 7: Develop CRUD APIs according to data models characteristics

Step 8: Create the journeys according to the sequence diagrams, with validating the pre-requisites

Step 9: Create APIs to validate product states

Step 10: Create Security model for the APIs

API Improvement model

As opposite figure, We have consumer and publisher, They are shared improvement the model, due to the required improvement after design, as a nature of any product lifecycle. 

Are You API First Company?

Since you have the following characteristics, you can consider yourself as API-First company:

1. You have APIs that operate and maintain your data models

2. You are providing you APIs as independent product

3. You make APIs available to your customers and partners as a source of your revenue stream

4. You know how to Manage and discover your APIs

5. You have standardized processes to build APIs

6. Your APIs is independent from any UX design

API Versioning

 What Is It?

API versioning is a practice in software development that involves managing and maintaining different versions of an Application Programming Interface (API). An API is a set of rules and protocols that allows one software application to interact with and request services or data from another software component, such as a web service or library. API versioning is essential to ensure that changes and updates to an API do not break existing clients or applications that rely on it.

Why?

• Compatibility

• Preventing Breaking Changes 

• Client Isolation

• Sunset enabling

• Business security and governance (Like creating API banking platform using API first, and then building the application upon)

So, it meet the strategic approach for the enterprise driven from the business transformation team, according to the following perspectives:

1. How will you build your upcoming products

2. How will your external entities integrate with your product

3. How will you monetize your product

4. How APIs will cover your overall business

Approaches

• Different deployment

• Headers

• URI routing

Process

Level 01:

•Change management

•Control integration touch points by TL

•Announcement model for integration touch points

•Application of unit testing for integration packages

Level 02:

• Apply selected Versioning streategy

• Enable support period for version minors (Quarter based)

• Backward compatibility according to release management process, which may be monthly, or quarterly or yearly

• Quarterly code refactoring process to reset minor version backward compatibility

• Handle legacy Versions : Responses and stoppage

Level 03:

• Application of design patterns: Aggregation pattern, to reduce the touch service, which gives the team the freedom for changing the signature

• API Catalog Model completeness, which should be deployed on API management platform, like SWAGGER, including its documentation

Level 04:

• Provisioning model for monetization: which will be used in the access of authentication and authorization, for the given tokens, to enable who can do what, and enrich monetization of your exposed APIs

• API Versioning Consolidation 

The practice is called API Version Consolidation or API Version Aggregation is mandatory when applying the API first approach.

Why it's needed:

1. Reduce maintenance overhead: Maintaining many versions leads to duplicated logic and higher testing costs.

2. Improve developer experience: Consolidated APIs are easier to understand, use, and document.

3. Encourage standardization: Forces consistency across versions, reducing divergence.

4. Simplify security and governance: Fewer versions mean fewer attack surfaces and simplified auditing.
   
   

Best Practices:

• Deprecate old versions with clear timelines

  1. 1. Review versions different scenarios

     2. Study scenarios consolidation approach

     3. Announce

     4. Cut-off date

     5. Staging testing

     6. Deploy together

• Use semantic versioning (v1, v2, etc.).

• Support backward compatibility within reason.

• Communicate changes transparently with API consumers.