Dear Malintha,
my responses below....
Best regards,
Frank
Am Mi., 6. Mai 2020 um 08:40 Uhr schrieb Malintha Amarasinghe <
malint...@wso2.com>:
> Dear Frank,
>
> Thank you for looking into this.
>
It is my pleasure :-)
>
> On Tue, May 5, 2020 at 1:48 PM Frank Leymann <fr...@wso2.com> wrote:
>
>> Dear Meruja,
>>
>> the URI of the second API (i.e. /me/roles/{roleName}) is really
>> debatable: the intent of the */me* part of the URI seems to be to
>> identify the logged-in user, and to me, such a user is a resource.
>>
> I may be a little bit deviating from the original question.
>
Let me add to the above: a URI, e.g. /me, always points to a single, a
unique resource. Thus, /me would point to exactly one person - we can't use
/me as an abstraction for all users implicitly picking the one who is
currently in the context (i.e. logged-in), that would counter the concept
of a URI as an identifier.
If we use a resource like /me, if we consider we do GET for that, we'll get
> the "me" resource which will return the logged in user details: eg:
> {
> "uid": "malintha"
> "fullName": "Malintha Amarasinghe"
> "mobile: "..",
> "roles" : [
> {
> "name" : "Internal/subscriber",
> "type": "Internal"
> }, {
> {
> "name" : "app-manager",
> "type": "Primary"
> }
> ],
> ...
> }
>
> In the above resource, I was under the impression that we consider "roles"
> as a sub-resource of /me. For example: if we did a GET for /me/roles we
> could return:
> {
> "count" : 2,
> "list": [
> {
> "name" : "Internal/subscriber",
> "type": "Internal"
> }, {
> {
> "name" : "app-manager",
> "type": "Primary"
> }
> ]
> }
>
> I think /me/roles/{roleName} may not make sense here because we could just
> do /roles/{roleName} to get the role details.
>
Just using /roles/{roleName} would return the details of the specified
role itself, without any reference to the logged-in user, i.e. the context
has to contain the user itself.
> Instead, I was under impression that we can use /me/roles?{roleName} to
> check if a particular role is available to the logged-in user.
>
...and, yes, you are absolutely right, "role" is a query parameter, i.e.
.../roles?{roleName} is the correct syntax (I left out the /me part by will
;-)).
>
> Would the above approaches be wrong? If so, if I need to get the roles of
> a particular user, should I only use an approach like /roles?{UserID}?
>
/roles?{UserId} will work too, but it would return all roles of the
specified user.
>
>
> I.e I assume that a user is represented in APIM as a resource (but I
>> didn't check the current API), or has a unique UserID - correct?
>>
>
> Yes, that is correct. But here, if we only need to represent the logged-in
> user, would it be ok if we have a resource /me (which represents a single
> resource for /users/<my-username>)?. In that case, that doesn't take
> username as an input and we don't need to validate whether the user has
> provided his username instead of providing a different one.
>
As argued above, a URI is not abstract, i.e. it can not point to different
resources (users in this case). Even worse, if multiple users use the API
at the same time, the "/me" URI would identify (!) different users at the
same time: which shows that it's no longer an identifier.
>
>
>> Thus, the URI of the API should be something like
>> .../users/{UserID}?{roleName} or /roles/{roleName}?{UserID}.
>>
>
> In this case, are we adding a filter for /users/{UserID} resource?
>
Yes, the query parameter ?{UserID} would act as a filter
> Which means if we did a GET /users/malintha?roleName=subscriber, should we
> give a 404 or 204?
>
Yes, we'll return a 404 if GET .../users/{UserID}?{roleName} did not find
the roleName specified for the UserID. But should more specific, returning
- a 403 Forbidden if the user is not allowed to issue this request (e.g.
because User_1 wants to check the role of User_2 - but I don't know whether
this is in sope of our application semantics)
- a 401 Unauthorized if the user has to authenticate him/herself, or
when authentication failed. But I am not sure whether this may happen
because of the "security" header, i.e. whether this has been verified
before.
> Can you kindly elaborate on this?
> I am sorry about asking multiple questions :( but thought of asking all as
> this will be helpful for us when designing new resources in the future too.
>
Continue asking questions: that's how we can jointly learn and build
fantastic products! If you want, you can send questions whenever you are
in doubt about design decision - I am happy to help :-))
>
> Thanks!
> Malintha
>
>
>>
>> Best regards,
>> Frank
>>
>>
>
>
>>
>>
>>
>> Am Di., 5. Mai 2020 um 06:17 Uhr schrieb Meruja Selvamanikkam <
>> mer...@wso2.com>:
>>
>>> Hi All,
>>>
>>> We are planning to add a REST API endpoint to APIM 3.2.0 Admin Rest APIs
>>> and the intention is to check the existence of a particular role name (
>>> Internal/subscriber) when transferring ownership of an application to a
>>> user. We have similar API in the publisher to check the availability of
>>> the role[1].
>>> We have to decide the OAuth2 scope which functionalities are used by
>>> Admin.
>>>
>>> The swagger definition for the new endpoint would be as follows:
>>>
>>> ######################################################
>>> # The Role Name Existence
>>> ######################################################
>>> /roles/{roleName}:
>>> #-----------------------------------------------------
>>> # The role name existence check resource
>>> #-----------------------------------------------------
>>> head:
>>> security:
>>> - OAuth2Security:
>>> - apim:<To_be_added>
>>> summary:
>>> Check given role name already exists
>>> description:
>>> Using this operation, to check whether given role already exists
>>> parameters:
>>> - $ref : '#/parameters/roleName'
>>> responses:
>>> 200:
>>> description:
>>> OK.
>>> Requested role name is returned.
>>> 404:
>>> description:
>>> Not Found.
>>> Requested role name does not exist.
>>>
>>> ######################################################
>>> # The Role Name Existence for the logged-in user
>>> ######################################################
>>> /me/roles/{roleName}:
>>> #-----------------------------------------------------
>>> # Validate role against a user
>>> #-----------------------------------------------------
>>> head:
>>> security:
>>> - OAuth2Security:
>>> - apim:<To_be_added>
>>> summary:
>>> Validate whether the logged-in user has the given role
>>> description:
>>> Using this operation, logged-in user can check whether he has given
>>> role.
>>> parameters:
>>> - $ref : '#/parameters/roleName'
>>> responses:
>>> 200:
>>> description:
>>> OK.
>>> Logged-in user has the role.
>>> 404:
>>> description:
>>> Not Found.
>>> Logged-in user does not have the role.
>>>
>>> Appreciate any feedback on this and correct me if I am wrong.
>>>
>>> [1] - [APIM-3.0] Publisher rest API to check a role name existence
>>>
>>> Thanks & Regards,
>>> *S.Meruja* |Software Engineer | WSO2 Inc.
>>> (m) +94779650506 | Email: mer...@wso2.com
>>> Linkedin: https://www.linkedin.com/in/meruja
>>> <https://www.google.com/url?q=https://www.linkedin.com/in/meruja>
>>> Medium: https://medium.com/@meruja
>>> <http://wso2.com/signature>
>>> _______________________________________________
>>> Architecture mailing list
>>> Architecture@wso2.org
>>> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
>>>
>> _______________________________________________
>> Architecture mailing list
>> Architecture@wso2.org
>> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
>>
>
>
> --
> Malintha Amarasinghe
> *WSO2, Inc. - lean | enterprise | middleware*
> http://wso2.com/
>
> Mobile : +94 712383306
>
_______________________________________________
Architecture mailing list
Architecture@wso2.org
https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
