Enhancement: api-root to act as a bookmark

[Kevsy]

Problem description

This enhancement proposes that the api-root URI should host an API catalogue resource, to facilitate discovery of CAMARA APIs - by both human developers and automated machine processes.

As well as benefiting API consumers, this can also help aggregators, industry bodies, and CAMARA itself know the state of deployment of CAMAAR APIs per operator.

Possible evolution

GET {api_root} to return a machine-readable set of links to the operator's CAMARA endpoints, associated metadata, and (optionally) non-CAMARA endpoints. This supports the HATEOAS principle of REST, i.e. "A REST API should be entered with no prior knowledge beyond the initial URI (bookmark)"

The machine-readable format will need to apply a semantic binding of each operator's API endpoint to the CAMARA API definition it implements. For example, a JSON Resource Descriptor utilising RFC 8288 extension relation types snippet:

 "links" : [
   {
     "rel" : "http://openid.net/specs/connect/1.0/issuer",
     "href" : "https://auth.operator.com"
   },
   {
     "rel" : "https://camaraproject.org/location-verification",
     "href" : "https://api.operator.com/camara/location-verification/v1"
   },
   {
     "rel" : "https://camaraproject.org/location-retrieval",
     "href" : "https://api.operator.com/camara/location-retrieval/v1"
   },
   {
     "rel" : "https://camaraproject.org/number-verification",
     "href" : "https://api.operator.com/camara/number-verification/v1"
   }
 ]

Alternative solution

This guidance could be added to API Design Guidelines as an Appendix, or Commonalities could consider an 'implementation guidelines' document in case there is sufficient interest/benefit.

Additional context

[uwerauschenbach]

Hi Kevin, an alternative could be to use a discovery scheme such as (Open)CAPIF. Further, and independent, I have two questions on your proposal: 1) wouldn't the hrefs be local to API root by default, apart from e.g. the related security / token endpoint? 2) where is the semantics of the rel URIs defined? Kind regards, Uwe Sent using Outlook for Android<https://aka.ms/AAb9ysg> - typos probably auto-generated

…

________________________________ Von: Kevin Smith ***@***.***> Gesendet: Mittwoch, September 4, 2024 6:35:21 PM An: camaraproject/Commonalities ***@***.***> Cc: Subscribed ***@***.***> Betreff: [camaraproject/Commonalities] Enhancement: api-root to act as a bookmark (Issue #294) Problem description This enhancement proposes that the api-root URI should host an API catalogue resource, to facilitate discovery of CAMARA APIs - by both human developers and automated machine processes. As well as benefiting API consumers, this can also help aggregators, industry bodies, and CAMARA itself know the state of deployment of CAMAAR APIs per operator. Possible evolution GET {api_root} to return a machine-readable set of links to the operator's CAMARA endpoints, associated metadata, and (optionally) non-CAMARA endpoints. This supports the HATEOAS principle of REST, i.e. "A REST API should be entered with no prior knowledge beyond the initial URI (bookmark)"<https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven> The machine-readable format will need to apply a semantic binding of each operator's API endpoint to the CAMARA API definition it implements. For example, a JSON Resource Descriptor<https://www.rfc-editor.org/rfc/rfc7033#page-11> utilising RFC 8288 extension relation types<https://www.rfc-editor.org/rfc/rfc8288.html#section-2.1.2> snippet: "links" : [ { "rel" : "http://openid.net/specs/connect/1.0/issuer", "href" : "https://auth.operator.com" }, { "rel" : "https://camaraproject.org/location-verification", "href" : "https://api.operator.com/camara/location-verification/v1" }, { "rel" : "https://camaraproject.org/location-retrieval", "href" : "https://api.operator.com/camara/location-retrieval/v1" }, { "rel" : "https://camaraproject.org/number-verification", "href" : "https://api.operator.com/camara/number-verification/v1" } ] Alternative solution This guidance could be added to API Design Guidelines as an Appendix, or Commonalities could consider an 'implementation guidelines' document in case there is sufficient interest/benefit. Additional context — Reply to this email directly, view it on GitHub<#294>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/AAKRTHO6CZFKTTYZ4WHJMBDZU4ZENAVCNFSM6AAAAABNUWQYDOVHI2DSMVQWIX3LMV43ASLTON2WKOZSGUYDKOBTGQ3DKNA>. You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[Kevsy]

HI @uwerauschenbach

an alternative could be to use a discovery scheme such as (Open)CAPIF

...or as a complement to CAPIF. This is a simple proposal which should be quick and straightforward to implement, and I can see it co-existing with (or preceding) CAPIF implementations. Where additional discovery mechanisms do not incur a significant overhead, then I think they can only be of benefit :)

1. wouldn't the hrefs be local to API root by default, apart from e.g. the related security / token endpoint?

I was following the recommendation in RFC 9264 :

"For the link context ("anchor" attribute) and link target ("href" attribute), use URI references that are not relative references (as defined in Section 4.1 of RFC3986.

...but, that would only apply if the document was a strict RFC9264 linkset. One for further discussion if the idea is accepted.

2. where is the semantics of the rel URIs defined?

Either IANA - which I have not chosen here, because each API would require a separate rel registration - or at the URI itself. This is an optional step per RFC 5988 , but I think it makes sense for e.g. https://camaraproject.org/location-verification to return a short description of the purpose of the CAMARA location verification API . Or the semantic could be bound by the URI being a pointer to a specific CAMARA OAS definition, e.g. https://camaraproject.org/location-verification/v1.0/location-verification.yaml, which is probably better. But again one for discussion as required.

[rartych]

Could it be covered by Runtime Restrictions API:

• Proposal - Runtime Restrictions API #183 ?

[bigludo7]

Hi @Kevsy
Do you see that as a complete distinct thing that the Telco Finder definition done in GSMA?
for me there are some overlap on the data provided and probable consumer of this service but anyway good topic to be discussed...

[Kevsy]

HI @rartych

Could it be covered by Runtime Restrictions API:

• Proposal - Runtime Restrictions API #183 ?

The proposal applies at the api-root level, so it does not require a specific API to be implemented to support it.

Also, the current scope for Runtime Restrictions appears to be a different scope: to expose 'optional capabilities/features/parameters are supported and enabled ' at the per-API level, rather than exposing the API catalogue for that operator.

But, if the scope for Runtime Restrictions extends to cover that too, then I think my proposal can be a source of information that the Runtime Restrictions API can utilise. E.g. I think an API catalogue maps to the 'B' layer in the Footprint & Capabilities diagram.

[Kevsy]

Hi @Kevsy Do you see that as a complete distinct thing that the Telco Finder definition done in GSMA? for me there are some overlap on the data provided and probable consumer of this service but anyway good topic to be discussed...

Hi @bigludo7

I think there is some overlap, but no conflict. For example, Telco Finder could GET api-root and quickly parse the available CAMARA APIs for that operator. It also means that CAMARA operators without Telco Finder can also expose an easy-to-find catalogue, and could make their migration to Telco Finder easier if they already have this approach in place.

[PedroDiez]

Hi,

@Kevsy I would like to understand which is the Business Case and the topic which is aimed to be resolved by this issue.

I mean, is this "catalogue resource feature" a topic raised by developers/aggregators in other Forum or is something raised in our own?

[Kevsy]

HI @PedroDiez , it is raised by me to:

1. follow REST (see the link in the first post, A REST API should be entered with no prior knowledge beyond the initial URI (bookmark)"
2. It is an easy way to help API Consumers with API discovery (the APIs offered by providers and the endpoints).

For GSMA OGW operators, this proposal is not intended to compete with Telco Finder, and could even work together with it.

If the {api_root} also hosts non-CAMARA APIs, then a response format with sematic binding (e.g. RFC 9264 ) can be used to distinguish between CAMARA and other APIs from that provider.