Establishing Unified API Design Approach Across Teams: Proposal and Strategy Discussion

[sachinvodafone]

Hi Team, We are currently engaged in multiple API design projects involving various teams. The challenge arises from each team operating independently and tackling design issues in their own unique manner, leading to a lack of synchronization in our overall approach. Common issues include (not limited to):

• Deciding to implement solution with different scopes or different endpoints.
• Determining whether to pursue a single API with multiple endpoints or to develop separate atomic APIs for distinct use cases.

To tackle this challenge, I propose the implementation of a standardized design pattern to address these common issues consistently across all teams at one place.

[nickvenezia]

Does a list exist of all available end points?

[bigludo7]

Hello @sachinvodafone
Don't you think that what is described here could help?
Even if this is focused for this Device status the arguments here seems to me very generic.

[PedroDiez]

Hello all,

Would like to understand the purpose/objective of this item.
Is it to discuss about design model regarding APIs that have subscriptions?

[sachinvodafone]

Hi @PedroDiez
Let me illustrate what I'm suggesting with an example:
In the 'DeviceIdentifier' API project, we had to decide between using different endpoints or scopes. After discussing it thoroughly, we opted for different endpoints and provided the reasons behind our decision.

Similarly, we encountered various design issues in the 'DeviceStatus' project (as mentioned by @bigludo7 ) and chose the best approach based on our team's experience and input.
Now, if another API project faces a similar challenge, they won't need to start from scratch. Instead, they can refer to our shared guideline to see how we tackled the issue. This allows them to understand our decision-making process and make their own informed choices without needing to begin a new discussion.

[PedroDiez]

Thanks for the clarifications @sachinvodafone.

Generally Speaking, we think it is better separate endpoints/APIs, when trying to cover a wide-scope functionality. Mainly for two reasons:

• One is maintainability, big APIs are expected to be evolved more frequently, whilst little ones, once well defined are expected to be more stable in time. This is a technical-based reason and also helps Operators to perform implementations that can be up&running more time.
• When API has subscriptions, we also see them as a separate "API" basepath, so as it provides flexibilixty for an Operator to schedule Backend Business Logic and Notifications in a separate Roadmap according to their needs.

On the Business side, "little" APIs also help Operators to look for agreements regarding the implementation of a given API version, providing more value to that feature as enforcing it to be implemented fully and widely. On the other hand, huge APIs have constrains to achieve it by their nature, as probably may lead towards situations where the whole API is more probably to cannot be implemented by Operator due to business priority, business scope (it does not apply) or maturity of systems; where at the end, discussions about performing non-complete implementation and how to deal with it have to be covered, which also adds complexity for the go-to-market path. Truly think we should avoid this as far as possible.