Hi Gimantha,
Don't we need to maintain a version with an API?
Regards
Roshan
On Fri, Feb 13, 2015 at 3:08 AM, Gimantha Bandara <giman...@wso2.com> wrote:
> Hi all,
> I changed the APIs so they follow the convention and i tested if there are
> conflicts between some APIs. JAX RS treats *GET
> /analytics/tables/{tableName}/{from} *, *GET
> /analytics/tables/{tableName}/recordcount *and *GET
> /analytics/tables/{tableName}/indices* as different APIs, so there will
> not be any conflict.
>
> Changed APIs :
>
> 1. Create a table
> *POST /analytics/tables*
> {
> tableName : "<table-name>"
> }
> ; table-name - The name of the table to be created.
>
> 2. Delete a table.
> *DELETE /analytics/tables*/*{tableName}*
>
> ; tableName - The name of the table to be deleted.
>
> 3. Check if a table exists
> *GET /analytics/tables?tableName=<table-name>*
> ; table-name - 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/tables/{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
>
> 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", (optional),
> "tableName": "tableName1",
> "timestamp": "<long-value>", (optional)
> "values":
> {
> "columnName1": "value1",
> "columnName2": "value2"
> }
> },
> {
> "tableName": "tableName2",
> "values":
> {
> "columnName1": "value1",
> "columnName2": "value2"
> }
> },
> ]
>
> 8. Delete records
> *DELETE /analytics/tables/{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.
>
> 9. Update a set of records
> *PUT /analytics/records* ( PATCH will be more suitable, but jax rs does
> not give PATCH method out of the box so we have to implement it)
> ; Content - As same as the POST method for creating records
>
> 10. Get the record count of table
> *GET /analytics/tables/{tableName}/recordcount*
> ; tableName - The name of the table
>
> 11. Create Indices for a table
> *POST /analytics/tables/{tableName}/indices*
> ; 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/tables/{tableName}/indices*
> ; 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/tables/{tableName}/indices*
> ; 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"
> }
>
> On Wed, Jan 21, 2015 at 8:38 AM, Anjana Fernando <anj...@wso2.com> wrote:
>
>> Hi Gimantha,
>>
>> You haven't really replied to Sinthuja's points there. We have to decide
>> if we are going ahead with Sinthuja's suggestions, or not. Lets first
>> educate ourselves on the best practices of RESTful API design a bit,
>> Googling helps [1]. For example, I'm also not sure if should be
>> /analytics/{tableName}/records or /analytics/records/{tableName}, each has
>> benefits, like, first approach can have ambiguity issues, specially when
>> there other operations with optional fields. And also, I guess we will need
>> to have /analytics/tables/{tableName} for creating tables etc.. or else,
>> for example when we do a POST for like "/analytics/T1", it may not be that
>> informative what we are actually doing there.
>>
>> [1]
>> https://www.google.com/search?q=REST+service+design&gws_rd=ssl#q=REST+api+design
>>
>> Cheers,
>> Anjana.
>>
>> On Wed, Jan 21, 2015 at 3:35 AM, Gimantha Bandara <giman...@wso2.com>
>> wrote:
>>
>>> Hi,
>>> Goood point!. Initially the search was implemented such a way that it
>>> returns a list of ids of records that match the query. Now the search
>>> method is changed, so it returns the records. So +1 for removing the API
>>> #6.
>>>
>>> @Sinduja, @Harshan
>>> Thanks for the reference links and for the feedback.
>>>
>>> On Tue, Jan 20, 2015 at 6:52 PM, Harshan Liyanage <hars...@wso2.com>
>>> wrote:
>>>
>>>> Hi Gimantha,
>>>>
>>>> Could you please explain the use-case for the API #6? IMO there should
>>>> not be any operation to fetch a list of records by ids. Instead there could
>>>> be an API which sends a list of records as the response for a query.
>>>>
>>>> For the API #14 you can still use GET method with query strings. I
>>>> think you have included start & count parameters to control the pagination.
>>>> For that you can use the HTTP range-header [1] or link headers as mentioned
>>>> in [2].
>>>>
>>>> [1]. http://otac0n.com/blog/2012/11/21/range-header-i-choose-you.html
>>>> [2]. https://developer.github.com/v3/#pagination
>>>>
>>>> Regards,
>>>>
>>>> Lakshitha Harshan
>>>> Software Engineer
>>>> Mobile: *+94724423048*
>>>> Email: hars...@wso2.com
>>>> Blog : http://harshanliyanage.blogspot.com/
>>>> *WSO2, Inc. :** wso2.com <http://wso2.com/>*
>>>> lean.enterprise.middleware.
>>>>
>>>> On Tue, Jan 20, 2015 at 6:34 PM, Gimantha Bandara <giman...@wso2.com>
>>>> wrote:
>>>>
>>>>> Hi Harshan,
>>>>>
>>>>> Thanks for the feedback. The list of IDs of the records to be
>>>>> retrieved can be too long. So setting a list of ids as a query param is
>>>>> not
>>>>> convenient. Even for the Search, we have to pass a query, which can be too
>>>>> long. Thats why the post method is used for Search.
>>>>>
>>>>> Thanks,
>>>>>
>>>>> On Tue, Jan 20, 2015 at 12:52 PM, Sinthuja Ragendran <
>>>>> sinth...@wso2.com> wrote:
>>>>>
>>>>>> 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
>>>>>>
>>>>>>
>>>>>>
>>>>>
>>>>>
>>>>> --
>>>>> Gimantha Bandara
>>>>> Software Engineer
>>>>> WSO2. Inc : http://wso2.com
>>>>> Mobile : +94714961919
>>>>>
>>>>
>>>>
>>>
>>>
>>> --
>>> Gimantha 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
>>>
>>>
>>
>>
>> --
>> *Anjana Fernando*
>> Senior Technical Lead
>> WSO2 Inc. | http://wso2.com
>> lean . enterprise . middleware
>>
>> _______________________________________________
>> 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
>
> _______________________________________________
> Architecture mailing list
> Architecture@wso2.org
> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
>
>
--
Roshan Wijesena.
Senior Software Engineer-WSO2 Inc.
Mobile: *+94719154640*
Email: ros...@wso2.com
*WSO2, Inc. :** wso2.com <http://wso2.com/>*
lean.enterprise.middleware.
_______________________________________________
Architecture mailing list
Architecture@wso2.org
https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
