Should we allow users to comment on APIs which belong to different tenants? If not we can remove '#/parameters/requestedTenant' from POST operation. IMO this is not required as if we need to comment on an api we need to login to the particular tenant. Hence +1 to remove '#/parameters/requestedTenant' from POST operation.
Thanks & Regards, Ishara Cooray Associate Technical Lead Mobile : +9477 262 9512 WSO2, Inc. | http://wso2.com/ Lean . Enterprise . Middleware On Thu, Aug 15, 2019 at 5:45 AM Ishara Cooray <[email protected]> wrote: > Hi, > > username: >>> type: string >>> description: | >>> If username is not given user invoking the API will be taken as >>> the username. >>> >>> Regarding the description: I guess we should omit it when posting a > comment and always use the logged-in user? > +1 > >> content: >>> type: string >>> createdTime: >>> type: string >>> example: 2017-02-20T13:57:16.229 >>> createdBy: >>> type: string >>> >>> I guess we don't need two properties: createdBy and username? > Are we allowing admin or the provider to edit the comment? > If so it make sense to have both username and createdBy. > > @Kavishka Fernando <[email protected]> > Let's add operationId to the definition as a convention. > > Thanks & Regards, > Ishara Cooray > Associate Technical Lead > Mobile : +9477 262 9512 > WSO2, Inc. | http://wso2.com/ > Lean . Enterprise . Middleware > > > On Tue, Aug 13, 2019 at 7:19 PM Malintha Amarasinghe <[email protected]> > wrote: > >> >> >> On Tue, Aug 13, 2019 at 6:06 PM Thilini Shanika <[email protected]> >> wrote: >> >>> Shouldn't we add error handling for unauthorized/forbidden API(Role >>> restricted) comment retrievals/deletions >>> >> +1 >> >> >> Also please find a couple of inline comments: >> >>> >>> On Tue, Aug 13, 2019 at 5:10 PM Kavishka Fernando <[email protected]> >>> wrote: >>> >>>> Hi all, >>>> >>>> We are planning on creating the comments feature for the Store in APIM >>>> 3.0 similar to the comments feature and outlook available in APIM-2.6.0. >>>> >>>> I am currently in the process of creating the REST API for the comments >>>> feature. >>>> Shown below is the swagger related to the resource, >>>> >>>> ###################################################### >>>> # The "Comments Collection" resource API >>>> ###################################################### >>>> '/apis/{apiId}/comments': >>>> #----------------------------------------------------- >>>> # Retrieve a list of all comments of a certain API >>>> #----------------------------------------------------- >>>> get: >>>> summary: Retrieve API comments >>>> security: >>>> - OAuth2Security: [] >>>> description: | >>>> Get a list of Comments that are already added to APIs >>>> parameters: >>>> - $ref: '#/parameters/apiId' >>>> - $ref: '#/parameters/limit' >>>> - $ref: '#/parameters/offset' >>>> >>>> We will need to add #/parameters/requestedTenant to retrieve comments >> of APIs which are in other tenant domains than the user's tenant. >> >>> tags: >>>> - Comments >>>> responses: >>>> 200: >>>> description: | >>>> OK. >>>> Comments list is returned. >>>> schema: >>>> $ref: '#/definitions/CommentList' >>>> 406: >>>> description: | >>>> Not Acceptable. The requested media type is not supported >>>> schema: >>>> $ref: '#/definitions/Error' >>>> >>>> #----------------------------------------------------- >>>> # Add a new Comment >>>> #----------------------------------------------------- >>>> post: >>>> summary: Add an API comment >>>> security: >>>> - OAuth2Security: >>>> - apim:subscribe >>>> x-scope: apim:subscribe >>>> parameters: >>>> - $ref: '#/parameters/apiId' >>>> - $ref: '#/parameters/requestedTenant' >>>> >>>> Should we allow users to comment on APIs which belong to different >> tenants? If not we can remove '#/parameters/requestedTenant' from POST >> operation. >> >> >>> - in: body >>>> name: body >>>> description: | >>>> Comment object that should to be added >>>> required: true >>>> schema: >>>> $ref: '#/definitions/Comment' >>>> tags: >>>> - Comments >>>> responses: >>>> 201: >>>> description: | >>>> Created. >>>> Successful response with the newly created object as entity in >>>> the body. >>>> Location header contains URL of newly created entity. >>>> schema: >>>> $ref: '#/definitions/Comment' >>>> headers: >>>> Location: >>>> description: | >>>> Location to the newly created Comment. >>>> type: string >>>> ETag: >>>> description: | >>>> Entity Tag of the response resource. Used by caches, or in >>>> conditional request. >>>> type: string >>>> 400: >>>> description: | >>>> Bad Request. >>>> Invalid request or validation error. >>>> schema: >>>> $ref: '#/definitions/Error' >>>> 415: >>>> description: | >>>> Unsupported media type. >>>> The entity of the request was in a not supported format. >>>> schema: >>>> $ref: '#/definitions/Error' >>>> >>>> >>>> >>>> ######################################################### >>>> # "Individual API comment" resource APIs >>>> ######################################################### >>>> '/apis/{apiId}/comments/{commentId}': >>>> >>>> #----------------------------------------------------------------------- >>>> # Retrieve an individual Comment for a certain API >>>> #----------------------------------------------------------------------- >>>> get: >>>> summary: Get details of an API comment >>>> security: >>>> - OAuth2Security: [] >>>> description: | >>>> Get the individual comment given by a username for a certain API. >>>> parameters: >>>> - $ref: '#/parameters/commentId' >>>> - $ref: '#/parameters/apiId' >>>> - $ref: '#/parameters/If-None-Match' >>>> >>>> Same as GET here: We will need to add #/parameters/requestedTenant >> >>> tags: >>>> - Comments >>>> responses: >>>> 200: >>>> description: | >>>> OK. >>>> Comment returned. >>>> schema: >>>> $ref: '#/definitions/Comment' >>>> headers: >>>> ETag: >>>> description: | >>>> Entity Tag of the response resource. >>>> Used by caches, or in conditional requests. >>>> type: string >>>> Last-Modified: >>>> description: | >>>> Date and time the resource has been modifed the last time. >>>> Used by caches, or in conditional requests. >>>> type: string >>>> 304: >>>> description: | >>>> Not Modified. >>>> Empty body because the client has already the latest version >>>> of the requested resource. >>>> 404: >>>> description: | >>>> Not Found. >>>> Requested comment does not exist. >>>> schema: >>>> $ref: '#/definitions/Error' >>>> 406: >>>> description: | >>>> Not Acceptable. >>>> The requested media type is not supported >>>> schema: >>>> $ref: '#/definitions/Error' >>>> >>>> #----------------------------------------------------- >>>> # Delete a particular Comment >>>> #----------------------------------------------------- >>>> delete: >>>> summary: Delete an API comment >>>> security: >>>> - OAuth2Security: >>>> - apim:subscribe >>>> x-scope: apim:subscribe >>>> description: | >>>> Remove a Comment >>>> parameters: >>>> - $ref: '#/parameters/commentId' >>>> - $ref: '#/parameters/apiId' >>>> - $ref: '#/parameters/If-Match' >>>> tags: >>>> - Comments >>>> responses: >>>> 200: >>>> description: | >>>> OK. >>>> Resource successfully deleted. >>>> 404: >>>> description: | >>>> Not Found. >>>> Resource to be deleted does not exist. >>>> schema: >>>> $ref: '#/definitions/Error' >>>> >>>> >>>> The resource will be as follows, >>>> >>>> #----------------------------------------------------- >>>> # The Comment resource >>>> #----------------------------------------------------- >>>> Comment: >>>> title: Comment >>>> required: >>>> - content >>>> properties: >>>> commentId: >>>> type: string >>>> >>>> Can make it just "id". >> >> >>> apiId: >>>> type: string >>>> >>>> I think apiId is not required. >> >>> username: >>>> type: string >>>> description: | >>>> If username is not given user invoking the API will be taken as >>>> the username. >>>> >>>> Regarding the description: I guess we should omit it when posting a >> comment and always use the logged-in user? >> >> >>> content: >>>> type: string >>>> createdTime: >>>> type: string >>>> example: 2017-02-20T13:57:16.229 >>>> createdBy: >>>> type: string >>>> >>>> I guess we don't need two properties: createdBy and username? >> >> Thanks! >> >> >>> Your input for this is highly appreciated. >>>> >>>> Thanks, >>>> *Kavishka Fernando* >>>> *Software Engineer | WSO2* >>>> Email: [email protected] >>>> Mobile: +94773838069 >>>> Web: http://wso2.com >>>> Blog: https://medium.com/@kavishkafernando >>>> >>>> <http://wso2.com/signature> >>>> >>> >>> >>> -- >>> Thilini Shanika >>> Associate Technical Lead >>> WSO2, Inc.; http://wso2.com >>> 20, Palmgrove Avenue, Colombo 3 >>> >>> >>> >> >> -- >> 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
