What should be returned when an endpoint is not implemented?

[trehman-gsma]

For example, DeviceStatus has /roaming, /connectivity, and /subscriptions. If an operator only chooses to implement /roaming, what should be returned for the remaining endpoints?

The CAMARA_common.yaml has a 501 NotImplemented example. I assume this should be used when an endpoint is not implemented - is anyone able to confirm?

  NotImplemented:
   description: Not Implemented
   content:
    application/json:
     schema:
      $ref: "#/components/schemas/ErrorInfo"
     example:
      status: 501
      code: NOT_IMPLEMENTED
      message: This functionality is not implemented yet

[mhfoo]

@trehman-gsma

The first step is to request for the access token, using a scope parameter which points to the targeted API.
The scope parameter is requested under 1) /authorize 2) /bc-authorize and 3) /token.

The access token is required to invoke the APIs.

1. If the YAML file contains multiple operations, then the path can be routed => 401 Unauthorized is returned always (hardcoded), access token will not have the scope of the API operation, which is not implemented.

2. If the YAML file is not deployed, then the path is not routable => 404 Not Found, using any access token

[bigludo7]

Hello @mhfoo
I would like to understand a bit more your perspective.

Suppose a Number verification implementation has implemented the /verify but not the /device-phone-number.

If an API consumer (not aware of this) wants to use this /device-phone-number, first a POST /authorize and the scope will be valued with openId dpv:xxxx number-verification:device-phone-number:read
Then the authorization server sent back a code.
Third, API consumer requests a Token.
Then, when the developer will consume this token for the /device-phone-number the server response will be

{
  "status": 403,
  "code": "INVALID_TOKEN_CONTEXT",
  "message": "Scope does not allow this operation"
}

Did i miss something there?
cc: @FabrizioMoggio

[rartych]

@AxelNennker @shilpa-padgaonkar Please have a look here.

[FabrizioMoggio]

I'm a bit confused, maybe I'm wrong, but 501 seems to me actually designed for this job. Or is it designed for something else?

[bigludo7]

I'm a bit confused, maybe I'm wrong, but 501 seems to me actually designed for this job. Or is it designed for something else?

Agreed on the principle @FabrizioMoggio but looking in detail on the sequencing of the 3-legs and the use of the access token, I guess your authorization server will not provide the right to claim data for an unavailable operation and so the 403 could be triggered before the 501.... but perhaps I missed something there.

[FabrizioMoggio]

if this is the case I suggest to implement anyway the method just to have it available and, once invoked, to provide back a message, like 501

[PedroDiez]

Hi all,

This situation should be avoided as far as possible.

APIs should be completely implemented and, in case there are endpoints that are likely to not be implemented by all operators for a known reason, then the best option would probably to generate APIs with less scope and have those endpoints in independent APIs that could be implemented by whoever can/require it.

Indeed, that is the approach that have been decided for the evolution of Device Status

[bigludo7]

Agreed on this rule @PedroDiez and I'm big supporter of the work in Device Status.
Meanwhile we do not have this situation in all other API like SIM Swap and Number Verification where you have 2 independent endpoints that can be fairly implemented one without the other....so we need a rule here.

[FabrizioMoggio]

@bigludo7 this is also the situation for Call Forwarding Signal too, isn't it? with two independent endpoints to get information on unconditional call fwd or for generic call fwd. I don't see two APIs for that but, as we are doing, one API with two endpoints to retrieve different "data" from the network. For the Traffic Influence API we are adding a new endpoint that provides an optional feature, a simplified way to invoke the TI API, I don't see this as an autonomous API either, we are adding a new endpoint to to implement a new operation in scope with the API. Because this new operation can not be easy implement, we decided to make it optional. I don't see a problem in documenting this new endpoint as optional, implementing it anyway as available interface that can provide back the expected result or "not implemented". Also considering that the API Consumer can be aware of the availability of the operation using the "Capabilities and Runtime Restrictions" API recently approved by TSC: camaraproject/WorkingGroups#401

[bigludo7]

Hello @FabrizioMoggio - Yes this is the same for CallForwarding.
We can have 501 in the yaml no problem for that.

My worry was more on the view from the developer. As I described before I'm afraid that 403 will be triggered before 501.

The "Capabilities and Runtime Restrictions" API of course provides useful information but we cannot assume all developer will consume this one on the fly before to make a call....

[uwerauschenbach]

Going back to the original problem which is that a particular endpoint / resource (URI) is not implemented by the server. The suggestion is to respond 501 Not implemented. This code is typically used to indicate functionality generally not supported, such as HTTP methods.

For a URI endpoint that the server isn't able to resolve, wouldn't 404 Resource not found be more appropriate?

[bigludo7]

@uwerauschenbach @FabrizioMoggio Getting feedback from colleague more involved in authorization pattern (and with RFC6749).

If take example of call-forwarding API we have defined 2 scopes: call-forwarding-signal:unconditional-call-forwardings:read and call-forwarding-signal:call-forwardings:read.
Suppose an implementation did not support /call-forwarding operation (the one protected by this second scope call-forwarding-signal:call-forwardings:read in CAMARA yaml)
As we have to use 3-legs, if an application requests for this /call-forwarding operation it will trigger a / authorize with a scope valued to openid dpv:blabla call-forwarding-signal:call-forwardings:read
This scope will not be know from the implementation authorization server... so the response will be a 302 but with errorType = invalid_scope and .... it's over.

[FabrizioMoggio]

@bigludo7 this is true if the endpoint is actually not implemented but we can avoid this: look at camaraproject/EdgeCloud#218 (comment)

[Kevsy]

Behaviour regarding Access Token Scope requests is covered by RFC 6749.

3.3 Access Token Scope

  If the client omits the scope parameter when requesting
   authorization, the authorization server MUST either process the
   request using a pre-defined default value or fail the request
   indicating an invalid scope.  The authorization server SHOULD
   document its scope requirements and default value (if defined).

Note this does not define behaviour if the scope is included but has an incorrect or unsupported value, but I believe the intent is the same: the scope is invalid because it is not supported. Hence:

5.2 Error Response:

The authorization server responds with an HTTP 400 (Bad Request)
   status code (unless specified otherwise) and includes the following
   parameters with the response:

invalid_scope
               The requested scope is invalid, unknown, malformed, or
               exceeds the scope granted by the resource owner.

So HTTP 400 with a response body indicating 'invalid_scope' appears to be the expected behaviour for the OAuth2 flow.

If there is any request to an API endpoint URI that is not implemented, I agree with Uwe that 404 Not Found is appropriate. RFC2616 501 Not Implemented is for another scenario:

   The server does not support the functionality required to fulfill the
   request. This is the appropriate response when the server does not
   recognize the request method and is not capable of supporting it for
   any resource.

[shilpa-padgaonkar]

Agree with the comment from @PedroDiez that this situation should be avoided as much as possible.

And if this does happen, then agree with the comment from @bigludo7 where the auth server will handle it.

[FabrizioMoggio]

just one consideration. we are evaluating two options in my understanding:

1. access denial to the endpoint in the authorization flow
2. authorization flow ok and the endpoint provides back an error code

in term of Documentation, to let the Developer understand what to expect, I feel the second option more adequate. it is, in my opinion, easier to explain in the documentation that and endpoint can not be supported and that, in this case, it provides back an error rather than explaining the authorization flow that is on top of the API and that is referenced in a standard way in the API documentation with a link to CAMARA official documents.

[bigludo7]

2. authorization flow ok and the endpoint provides back an error code

@FabrizioMoggio to be sure to get it, in this case, in the access token that you provide to your consumer you will value the scope attribute with a data claim for an operation that you did not implement ? correct?

[FabrizioMoggio]

2. authorization flow ok and the endpoint provides back an error code

@FabrizioMoggio to be sure to get it, in this case, in the access token that you provide to your consumer you will value the scope attribute with a data claim for an operation that you did not implement ? correct?

I have implemented it, the implementation is very simple and just provides back and error code, with an explanation, explaining that that operation is not supported. I see this easier to understand for the developer. it is managed by the YAML flow rather than on top of it.

[AxelNennker]

I interpret this sentence "what should be returned for the remaining endpoints?" as "we are past the authorization server" in this discussion.

The client is using an access token to call endpoint E and the telco has not implemented it.
The access token can't be valid because the authorization server would never issue an access token for an endpoint that is not implemented, right?
If the access token is in deed valid for that endpoint but the telco RS returns "not implemented" then I would consider this to be an internal error.

I think a telco cannot and must not "choose" to implement only some endpoints. When it comes to implementing a Camara API it is all-or-nothing.

[bigludo7]

The problem @AxelNennker is for multi endpoints API. Let's take the call fowarding signa API - we have /unconditional-call-forwardings endpoint and /call-forwardings. These 2 endpoints are independent. Nothing prevent an operator to only provide one.
Same in SIM Swap with the retrieve-date and the check endpoints.
Wondering if we should not have these in separate yaml....

[AxelNennker]

I think this should be viewed from the perspective of the client. Let's say the client buys API access in a market with four telcos and the client builds its product based on that API but the product fails for 1/4 of the users because one telco decided to not to implement some endpoints which might be essential for the product.
I think in one market there should always be the same API implemented by all participating telcos.
If the AZ knows that some endpoints are not implemented by some telcos, then the AZ should not return a authorization code and no access token for those scope/endpoints. Still, that API is then not worth the full money compared to when all telcos support all endpoints.
We can certainly have different yaml files for different subsets of implemented endpoints but in that set we have the same problem if one telco "chooses" not to implement some endpoint.

[FabrizioMoggio]

@AxelNennker you are totally right, it would be the best for the Developer to have all the endpoints implemented by all the Operators. Anyway, if the endpoint provides additional feature, not the main ones, how can we force an Operator to implement them? So I agree with @bigludo7 on this.

@bigludo7 on your comment #160 (comment) you show a very good solution when an endpoint is not implemented, my point is (#160 (reply in thread)) that we can have a different solution if the operator implements it with no real operation inside. My preference goes to this second option not for technical reasons but because, in my opinion it is easier to explain the flow in the documentation. Anyway mine is just a feeling, we can try to implement your solution in the Call FWD Signal API, document it, and see if it easy to understand.

[bigludo7]

We can certainly have different yaml files for different subsets of implemented endpoints but in that set we have the same problem if one telco "chooses" not to implement some endpoint.

In the 'concrete' cases that we have today for call forwarding signal & sim swap it solves the problem.

[AxelNennker]

With separate yaml files we are creating API_Variant1 and API_Variant2.
At onboarding time of the client we tell the AZ which yaml file is valid for that client_id, and when the client requests an authorization code for scope1 that is not in that API-variant the AZ does not issue the code.
So, there is no access token for that scope/endpoint created and access token validation at the RS fails. Even if the RS implemented the endpoint, right?

[AxelNennker]

Quote from CAMARA_common.yaml

GENERIC_501_NOT_IMPLEMENTED:
description: Service not implemented. The use of this code should be avoided as far as possible to get the objective to reach aligned implementations

[FabrizioMoggio]

Quote from CAMARA_common.yaml

GENERIC_501_NOT_IMPLEMENTED:
description: Service not implemented. The use of this code should be avoided as far as possible to get the objective to reach aligned implementations

That is a possible solution for my option 2 (authorization flow ok and the endpoint provides back an error code) #160 (reply in thread):

• one YAML
• endpoint exposed
• authorization OK
• 501 if not supported.

Obviously this should be avoided, we expect that every operator implements all the endpoints, but, for certain operations, that are ADDITIONAL features, it can be good to offer the capability.

Anyway this must be an exception and the CAMARA sub group teams must be very careful on this, creating a Discussion on business or technical reasons that leads to the adoption (or not) of an optional endpoint.

Another comment with the option 1 (access denial to the endpoint in the authorization flow) this can be done anyway by the Operator, even if we don't do anything in our code. Right? If this is correct, this solution, if preferred by the operator, is anyway on the table. We, as CAMARA, can provide a official solution with the "two YAML option" or with the "501" option.

[AxelNennker]

I think the discussion reached a point where somebody should write a PR to https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#3-api-definition

If an API has k optional features then we would have 2^k yaml files, each for that feature being "on" or "off". Do we have a business demand for optional features? Products sim-swap and sim-swap-deluxe?

If there is a demand, then we can technically implement this in the AZ and RS. The implementation of the AZ and RS seem straight forward. Actually, I think, there is not even some special handling needed for these cases.

I think "501 not implemented" should be regarded as an internal error (valid access token but still the telco has not implemented the endpoint). The AZ should never create an access token that leads to a 501.

Anyway, there should be some guideline in Commonalities regarding this.

[FabrizioMoggio]

why forcing an operator to implement all the additional operations. Currently, according to the Guidelines we have an easy solution, totally clear to the Developer:

endpoint returning 501: optional
endpoint not returning 501: mandatory

Why we should define in the Guidelines 501 and then using the AZ server to block an access to it. Anyway this can be a specific decision at implementation level

[FabrizioMoggio]

by the way, @AxelNennker, I agree with you, when the discussion is closed a PR on the Guidelines is required