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 <kavis...@wso2.com> 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 <malint...@wso2.com> wrote: > > > On Tue, Aug 13, 2019 at 6:06 PM Thilini Shanika <thili...@wso2.com> 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 <kavis...@wso2.com> >> 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: kavis...@wso2.com >>> 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 Architecture@wso2.org https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture