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
