Hi Gimantha,
I think following the conventions will be more intuitive to the users, and
we should have a proper reason to not follow. And the post request is
generally needs to be sent to create the object and the back end is going
to decide where to create the tables resource, therefore it should be POST
to '/analytics/tables' and message body should be having the table name. If
you want to use /analytics/{tableName}, then you should use PUT rather POST
[1]. But IMO POST is the most suitable operation for this context.
And through out the below given URL patterns, in order to fetch the records
from a table, you have used '/analytics/records/{tableName}' url pattern
where 'records' is in the middle and it is not the correct data hierarchy
and again I feel it's not the convention. Basically tables contains records
and not records contains tables. Therefore if we use
POST to '/analytics/tables' for create table, then you can use simply user
'analytics/{tableName}' to GET/POST for the tables, IMHO the records is
just an additional segment which is not needed to be here.
[1] http://restcookbook.com/HTTP%20Methods/put-vs-post
Thanks,
Sinthuja.
On Tue, Jan 20, 2015 at 1:29 AM, Gimantha Bandara <giman...@wso2.com> wrote:
> Hi Sinduja,
>
> Thank you for the feedback.
>
> On Mon, Jan 19, 2015 at 12:04 PM, Sinthuja Ragendran <sinth...@wso2.com>
> wrote:
>
>> Hi gimantha,
>>
>> Please see the comments inline.
>>
>> On Sun, Jan 18, 2015 at 11:24 PM, Gimantha Bandara <giman...@wso2.com>
>> wrote:
>>
>>> Hi,
>>> Currently, I am working on $subject. Basically the methods in
>>> AnalyticsDataService will be exposed through REST APIs. Please refer to
>>> Architecture mail thread "*[Architecture] BAM 3.0 Data Layer
>>> Implementation / RDBMS / Distributed Indexing / Search*" for more
>>> Details. Following are the supported REST APIs.
>>>
>>> 1. Create a table
>>> *POST /analytics/{tableName}*
>>> ; tableName - The name of the table to be created.
>>>
>>
>> IMHO the above should be POST to '/analytics/*tables*' and the request
>> content should have the table name as given below.
>> {
>> "tableName" : "Test"
>> }
>>
> Since the POST takes only the table name, it is straightforward to use it
> as a path parameter.
>
>>
>>> 2. Delete a table
>>> *DELETE /analytics/{tableName} *
>>> ; tableName - The name of the table to be deleted.
>>>
>>
>>> 3. Check if a table exists
>>> *GET /analytics/{tableName} *
>>> ; tableName - The name of the table being checked.
>>>
>>> 4. List All the tables
>>> *GET /analytics/tables*
>>> ;Response will be an JSON array of table names. e.g. [ "table1" ,
>>> "table2" , "table3" ]
>>>
>>> 5. Get the records from a table.
>>> *GET /analytics/records/{tableName}/{from}/{to}/{start}/{count} *
>>> ; tableName - The name of the table from which the records are retrieved.
>>> ; from - The starting time to get records from.
>>> ; to - The ending time to get records to.
>>> ; start - The paginated index from value
>>> ; count - The paginated records count to be read
>>> ; response - takes the format of the request content of No.7
>>>
>>
>> Do we need to have 'records' in the URL? I think it's better to have
>> */analytics/{tableName}/{from}/{to}/{start}/{count}
>> *
>>
>
> "records" is there to avoid conflicts with other contexts. As an example,
> If we remove "records", the URL will take the format
> "/analytics/{tableName}", which is already a defined REST API.
>
>>
>>> 6. Get the records from a table (By IDs)
>>> *POST /analytics/records/{tableName}*
>>> ; tableName - The name of the table from which the records are retrieved.
>>> ; Content - A List of IDs of the records to be retrieved in the
>>> following format.
>>> [ "id1" , "id2" , "id3" ]
>>> ; response - takes the format of the request content of No.7
>>>
>>
>> Similarly can we have this as * /analytics/{tableName}?*
>>
>>>
>>> 7. Create records ( can be created in different tables or in the same )
>>> *POST /analytics/records*
>>> ; Content - A list of records in json format like in below.
>>> [
>>> {
>>> "id": "id1",
>>> "tenantId": -1234,
>>> "tableName": "tableName1",
>>> "timestamp": "yyyy-mm-dd hh:mm:ss",
>>> "values":
>>> {
>>> "columnName1": "value1",
>>> "columnName2": "value2"
>>> }
>>> },
>>> {
>>> "id": "id2",
>>> "tenantId": -1234,
>>> "tableName": "tableName2",
>>> "timestamp": "yyyy-mm-dd hh:mm:ss",
>>> "values":
>>> {
>>> "columnName1": "value1",
>>> "columnName2": "value2"
>>> }
>>> },
>>> ]
>>>
>>> 8. Delete records
>>> *DELETE /analytics/records/{tableName}/{timeFrom}/{timeTo}*
>>> ; tableName - Name of the table from which the records are deleted.
>>> ; timeFrom - The starting time to delete records from.
>>> ; timeTo - The end time to delete records to.
>>>
>>>
>> Again do we need to have 'records' in the middle? IMHO
>> /analytics/{tableName}/{timeFrom}/{timeTo} is better.
>>
>> 9. Update records
>>> *PUT /analytics/records*
>>> ; Content - As same as the POST method for creating records
>>>
>>> 10. Get the record count of table
>>> *GET /analytics/count/{tableName}*
>>> ; tableName - The name of the table
>>>
>>> 11. Create Indices for a table
>>> *POST /analytics/indices/{tableName}*
>>> ; tableName - The name of the table of which the indices are set
>>> ; Content - takes the following format. TYPE is one of "INTEGER",
>>> "BOOLEAN", "DOUBLE", "STRING", "FLOAT", "LONG"
>>> {
>>> "indexColumnName1" : "TYPE1",
>>> "indexColumnName2" : "TYPE2"
>>> }
>>>
>>
>>> 12. get the indices of a table
>>> *GET /analytics/indices/{tableName}*
>>> ; tableName - The name of the table
>>> ; Response will be of the format of the previous POST request's Content.
>>>
>>> 13. Clear the indices of a table
>>> *DELETE /analytics/indices/{tableName}*
>>> ; tableName - The name of the table
>>>
>>> 14. Search records of a table
>>> *POST /analytics/search*
>>> ; Content - takes the following format
>>> {
>>> "tableName": "sampleTableName",
>>> "language": "sampleLanguageName",
>>> "query": "sampleQuery",
>>> "start": "start-location-of-the-result",
>>> "count": "maximum-number-of-entries-to-return"
>>> }
>>>
>>
>> IMHO this should be a GET request.
>>
>
> Here the problem is, that the search method in AnalyticsDataService takes
> few parameters. If we are to implement it as a GET, then we will have to
> put all the parameters in the URL itself.
>
>>
>>
>> Thanks,
>> Sinthuja.
>>
>>
>>> If a method does not have a specific response mentioned above, the
>>> response will take the following format.
>>>
>>> {
>>> "status" : "statusValue",
>>> "message" : "sampleMessage"
>>> }
>>>
>>> Suggestions and feedbacks are appreciated.
>>>
>>> Thanks,
>>>
>>> --
>>> Gimanthaa Bandara
>>> Software Engineer
>>> WSO2. Inc : http://wso2.com
>>> Mobile : +94714961919
>>>
>>> _______________________________________________
>>> Architecture mailing list
>>> Architecture@wso2.org
>>> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
>>>
>>>
>>
>>
>> --
>> *Sinthuja Rajendran*
>> Senior Software Engineer <http://wso2.com/>
>> WSO2, Inc.:http://wso2.com
>>
>> Blog: http://sinthu-rajan.blogspot.com/
>> Mobile: +94774273955
>>
>>
>>
>> _______________________________________________
>> Architecture mailing list
>> Architecture@wso2.org
>> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
>>
>>
>
>
> --
> Gimantha Bandara
> Software Engineer
> WSO2. Inc : http://wso2.com
> Mobile : +94714961919
>
--
*Sinthuja Rajendran*
Senior Software Engineer <http://wso2.com/>
WSO2, Inc.:http://wso2.com
Blog: http://sinthu-rajan.blogspot.com/
Mobile: +94774273955
_______________________________________________
Architecture mailing list
Architecture@wso2.org
https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
