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
