Dear Frank, Thank you very much. Please find my inline response.
On Sat, May 9, 2020 at 2:22 PM Frank Leymann <[email protected]> wrote: > Dear Malintha, > > my responses below.... > > Best regards, > Frank > > > > > Am Mi., 6. Mai 2020 um 08:40 Uhr schrieb Malintha Amarasinghe < > [email protected]>: > >> Dear Frank, >> >> Thank you for looking into this. >> > > It is my pleasure :-) > > >> >> On Tue, May 5, 2020 at 1:48 PM Frank Leymann <[email protected]> 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. > I think this was copied from the SCIM spec /Me endpoint ( https://tools.ietf.org/html/rfc7644#page-66). I did some search regarding this and I found several responses saying "*any information that can be named can be a resource" *as per Roy Thomas Fielding's dissertation. It also says "A resource is a conceptual mapping to a set of entities, not the entity that corresponds to the mapping at any particular point in time." So according to this, can we consider that "the logged-in user from the context" as a conceptual mapping? (I am not sure I have correctly understood the word conceptual mapping :( ) If that is true, we can consider that as a resource. In that case, /me would be the unified locator for that conceptual mapping? https://stackoverflow.com/questions/36520372/designing-uri-for-current-logged-in-user-in-rest-applications https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_2_1_1 > 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. > Well noted above responses. >> >> 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) > > Yes, it makes sense. My only concern was having this validation because if we had a resource like /me this won't be required because /me represents the user in the context. > > - 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. > > Yes, the above is handled in a different layer. > >> 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 :-)) > Thank you again Frank :) Thanks! > > >> >> Thanks! >> Malintha >> >> >>> >>> Best regards, >>> Frank >>> >>> >> >> >>> >>> >>> >>> Am Di., 5. Mai 2020 um 06:17 Uhr schrieb Meruja Selvamanikkam < >>> [email protected]>: >>> >>>> 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: [email protected] >>>> 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 >>>> [email protected] >>>> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture >>>> >>> _______________________________________________ >>> Architecture mailing list >>> [email protected] >>> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture >>> >> >> >> -- >> Malintha Amarasinghe >> *WSO2, Inc. - lean | enterprise | middleware* >> http://wso2.com/ >> >> Mobile : +94 712383306 >> > -- Malintha Amarasinghe *WSO2, Inc. - lean | enterprise | middleware* http://wso2.com/ Mobile : +94 712383306
_______________________________________________ Architecture mailing list [email protected] https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
