Multiple endpoints or multiple API within one API 'Family'?

[bigludo7]

Hello

We have a pattern question in Device location (that was also raised in device status) that probably require a global gouvernance.

As of now we have one feature in this API: Check Device Location. We'll add subscription management but globally this is always same function to check where is a device with a geo location provided as input.

We have a request to add another feature: Provides (Get) Device location (I will not comment on privacy in this issue). This is a distinct feature .

We are hesitating on the pattern:

1. Keep one API (Device location ) and provide distinct endpoint in the OAS (one for check and for for get)
2. Describe a second API within Device Location family focused only on this get function

Solution 1. seems the more straightforward are both features are very close... but with additional thinking solution 2. bring flexibility for versioning but also to expose clearly to developer the capabilities (indeed if a Telco offers the check but not the get, this is explicit with solution 2 while in solution 1, except if we add a home resource, developer will get a 501).

Same debate occurs in device status with roaming and connectivity.

cc: https://github.com/jlurien https://github.com/monamok

[jordonezlucena]

TEF stand is option 2. The more atomic/granular API definition, the easier to make progress on versioning/releasing (or to deprecate features that didn't succeed).

[akoshunyadi]

We from DT think that APIs shouldn't be atomic which would cause a big overhead on both provider and user sides and also here in Camara.
Rather combine logically strongly related endpoints into 1 API. E.g. for DeviceStatus: /roaming and /connectivity or for DeviceLocation /verification and /position.

But for future we support the idea of splitting APIs to prevent too complex APIs.

[bigludo7]

In order to move forward on this topic we opened an issue on Device Status API there to get member feedback: camaraproject/DeviceStatus#34

I'm wondering if, finally, this question could be handled globally in Commonalities instead to be at API working group level. We can probably list in commonalities pros/cons for both pattern and make recommendation to pick one or the other depending on the case - but I doubt we can have a golden rule enforcing one pattern in all situation.

[eric-murray]

As this issue is still open, I'll comment that Vodafone's preference is for the second approach, where additional endpoints are implemented as separate APIs. The primary reason for this was flexibility in implementation and API management. However, it is recognised that both approaches could be made to work.

[sachinvodafone]

Type	Separate BasePath	Common BasePath	Vodafone’ Preference
API Consumer	Easier to navigate and understand the API. It can be easier for API consumers to find and understand the relevant endpoints for each status-specific API.		Not Critical
	Confuse API consumers If the different YAML files have overlapping functionality or endpoints.	Confuse API consumers if the "roaming" and "connectivity" statuses both have the ability to check the device's network status, then API consumers will not be able to easily determine which status to use.	Separate
Preference	if there are a large number of statuses, such as "battery level", "signal strength", and "location". May be more appropriate for APIs with highly specialized or unique functions. If southbound connectivity is different as it would be easy to maintain and manage each endpoint individually. if data needs to be isolated or protected in a specific way. If each endpoint has different authorization requirements.	if there are only two statuses, "roaming" and "connectivity". May be more appropriate for APIs with more general or standardized functions. If southbound connectivity are common for each endpoint as could lead to more complexity and potential conflicts between the different southbound systems if they are same. if all endpoints have the same authorization requirements.	Separate
Duplication of Effort and Code	There may be some duplication of effort and code across the different YAML files.	Minimal	Common
Simplicity	API definition can be simpler and more straightforward to understand and manage. Can keep each status-specific API more focused and easier to manage.	The API definition can become large and complex. It can be more difficult to maintain and update the API definition.	Separate
Separation of Concerns	Help with separation of concerns and keep the API definition organised and modular. Can better organise the API and keep each part of the API focused on its specific functionality.	May result in less modularity and separation of concerns, as different statuses are part of the same API.	Separate
Versioning	Easier to version and maintain each status-specific API independently without affecting other parts of the API.	Difficult	Separate
Maintenance Issues	More complex to manage multiple YAML files with separate endpoints and versioning.  Require additional effort in documenting, testing, and managing the different parts of the API. Fine-grained control over resource allocation.	More uniform allocation of resources across all services.	Separate
Design Principles:  Base	Microservices.	Monolithic.	Separate
Design Principles: Single Responsibility Principle (SRP)	Better	Poor	Separate
Design Principles: Loose Coupling (Minimal dependencies)	Better	Poor	Separate
Design Principles:High Cohesion (Related to each other)	Less	High	Separate
Testing	Easier to test each YAML file independently.	More complex to perform functional test on big YAML file	Separate
Maintainability	More	Minimum	Common
Monitoring and auditing	If detailed monitoring and auditing is required to allows for better separation of traffic and monitoring data		Separate
Performance	May lead to more network latency if clients need to make multiple requests to different endpoints in order to get all the information they need.	May lead to more processing overhead if we need to route requests to different microservices or if we need to apply different policies to different endpoints.	Neutral
Scalability	Easier	May make it more difficult to scale individual endpoints or microservices	Separate
Consistency	Easier to enforce consistency within each endpoint, but harder to maintain consistency across the API as a whole	Make it more difficult to enforce consistency when different teams or developers are responsible for different parts of the API.	Separate
Enforce Security Requirement	Easier if requirement are different for endpoints May provide greater isolation and easier security management.	May make it more difficult to apply different security policies or to restrict access to specific endpoints Easy to manage if security requirement are same across all endpoints may increase the attack surface and require more sophisticated security controls	Separate
Compliance	Easy to manage	If different compliance requirements for different statuses then it is harder to manage through the same YAML/basepath	Separate
Governance	May allow for more decentralized ownership and governance	May require more centralized governance and coordination across teams	Common
Development Effort	May require more development effort to implement. Provide greater agility and flexibility for individual teams.	Require less development effort. May be more rigid and less adaptable to individual team needs.	Common
Authentication and Authorization	Simpler	Complex	Separate
Data Privacy	Simpler	Complex	Separate
Retirement	Retiring separate APIs can be done independently, allowing for faster and more targeted retirement of services that are no longer needed.	Retiring common APIs requires careful coordination across all teams to ensure that all dependencies are identified and addressed before the API is deprecated.	Separate
Change management	Each separate API can be updated independently, allowing for more flexibility and agility in responding to changing business needs.	Changes to common APIs can affect multiple teams, so careful planning and communication are important to minimize disruption.	Separate
Cross-cutting Concerns (e.g., security, rate limiting, caching for individual endpoint)	Simpler	Complex	Separate
Conflict Requirement		May lead to potential conflicts and challenges in maintaining consistency across different statuses. Conflicts can arise if there are conflicting requirements or functionality between different endpoints that share the same base path.	Neutral
Example	{apiRoot}/device-roaming-status/v0/roaming {apiRoot}/device-connectivity-status/v0/connectivity	{apiRoot}/device-status/v0/roaming {apiRoot}/device-status/v0/connectivity

[rartych]

Thank you @sachinvodafone for the exhaustive analysis.
I propose to convert this issue to discussion - this way it will be closed, but still visible and open for further comments.
What do you think @bigludo7 @akoshunyadi @eric-murray @jordonezlucena ?

[bigludo7]

Thank @sachinvodafone for this material
Agree with you @rartych to keep this as discussion. Future work on device status & device location API will leverage this.

[akoshunyadi]

In the working group of DeviceStatus API a document is prepared to store & discuss arguments and preferences of each company.