API Design Guidelines: Optional API Operation for the Operator

[FabrizioMoggio]

Considering camaraproject/EdgeCloud#218 (comment)

I can't see in the Guidelines this problem addressed. The question under discussion is: "Is it possible to define an operation as optional for the Operator to implement?" I mean, not a core feature of the API, but an additional one, that provides some more feature on top of the core ones. For the TI API we are introducing a new feature that is Automatic Mobility. The TI API, currently, must be invoked each time the UE moves among geographical areas (Zones or Regions). With this new feature the API Consumer can ask the API Producer to always apply the optimal routing. You can see that this feature is useful but not essential. Considering that this feature can be not easy to implement for the Operator, the idea is to provide this feature with a specific operation and to document it as optionally supported by the API Producer. This means that the API Consumer can get back "unsupported" when invoking the new method for Automatic Mobility. We are wondering if this is something that must be defined in the API Guidelines to have a homogeneous approach in CAMARA.

[gmuratk]

Hi Fabrizio,
#126 was opened and later changed to Discussion #183.
There is an open PR in the API Backlog for an API to be described to cover not only optionality (of parameters, operations, etc.), but also available capabilities based on changing conditions (in network, location, subscription, etc.)
camaraproject/WorkingGroups#401

It will be great to get your input!
cc: @lbertz02

[FabrizioMoggio]

I'm not sure to have got Discussion #183 correctly, is that a proposal for a new API to manage restrictions on another API? Or is it about how to manage restrictions in a generic API?

[gmuratk]

Separate API (service management API) to indicate [to API Consumer] what's restricted / not supported options [by an API Provider] in CAMARA service API(s) without having to create different yaml files. Example scenarios are provided in the slide deck referenced in the discussion link.

[FabrizioMoggio]

honestly I don't get why we need a specific API to provide information about the supported features of another API. It is even hard to maintain such an API that needs to be updated on the supported features from all the other CAMARA API. Maybe there is some automatic mechanisms that can be put in place, I suppose, otherwise I can't see how it can work :-) Anyway in my understanding such API is not started yet, (I couldn't find it in API Backlog).

Considering my proposal in the first post: "This means that the API Consumer can get back "unsupported" when invoking the new method for Automatic Mobility." Is it not a good practice for an APIs to provide back an output like "unsupported" when an operation is invoked?

Another question, which is the status of that API proposal? The discussion indeed appears frozen for a while now.

[gmuratk]

Proposal was reviewed and accepted to be treated as a new API by TSC. It is listed in the API backlog APIBacklog (listed as Capability and Runtime Restrictions)

I think API designs should consider error conditions, including but not limited to scenario you describe above, but if we can proactively let API consumers know if an optional [operation, parameter, etc.] is not supported or not available before they invoke and receive the error message, it will enhance the developer and end-user experience (e.g. enable/disable UI controls).

[FabrizioMoggio]

This can be closed because of the new API: Capability and Runtime Restrictions