Review webservice query parameter naming across all webservices

11945
Reporter: mdoering
Type: Task
Summary: Review webservice query parameter naming across all webservices
Priority: Critical
Resolution: Fixed
Status: Closed
Created: 2012-09-25 21:46:43.479
Updated: 2013-09-30 16:48:52.894
Resolved: 2013-01-14 16:11:39.255
        
Description: We started out in our api policy document with "The entire API will be case sensitive.  We will adopt the convention to build URLs as entirely lowercase.  Where parameters are two words they must be separated by underscore (e.g. fancy_name).

The http://dev.gbif.org/wiki/display/POR/Webservice+API mostly use lowerCamelCase parameters, so does the OccurrenceSearchParameter class values.
We should discuss again which naming convention we would like to see in our webservices.

My first proposal would be to use a case insensitive api with underscores. This makes it easy to transform query parameter names into enum members and vice versa.

Regardless of the exact naming convention this task should review all used parameters to make sure:
 - we use a consistent naming convention
 - we use the same parameter name for the same kind of parameter, e.g. always datasetKey not dataset, datasetID or checklistKey
]]>
    

Author: mdoering@gbif.org
Comment: first list inconsistencies
Created: 2012-11-21 12:42:00.949
Updated: 2012-11-21 12:42:00.949

Author: kbraak@gbif.org
Created: 2012-12-17 14:26:11.736
Updated: 2012-12-17 14:26:11.736
        
The following services use lowerCamelCase:

- Checklist Bank Services: Name usage (e.g. filter parameters: datasetKey, sourceId)
- Registry Services (Node, Organization, Network, Technical Installation, Dataset) (e.g. filter parameters: isoCountryCode, endpointType, etc)
- Occurrence Services: Occurrence Record (e.g. filter parameters: datasetKey)

The following services use lower case with underscores:

- Checklist Bank Services: Search Service
- Registry Services: Dataset Search Service

The following services use a mix of the above 2 conventions:

- Occurrence Services: Search Service (e.g. filter parameters: TAXON_KEY, datasetKey)
    

Author: kbraak@gbif.org
Created: 2012-12-17 15:17:42.795
Updated: 2012-12-17 15:17:42.795
        
I didn't find any inconsistencies with different parameter names referring to the same thing.

The API document currently has an unimplemented parameter for the Registry services called "isoCountryCode", whereas Dataset Search Service uses "country". This is a potential inconsistency.

I still need to open new issues to implement missing parameters across services. For example, implement filter parameter "isoCountryCode/country" for Organization, Network, and Technical Installation services. 
    

Author: kbraak@gbif.org
Created: 2013-01-02 14:18:58.134
Updated: 2013-01-02 14:18:58.134
        
New issues have been added for all missing parameters across services. These include:

REG-360
REG-361 (note added about potential inconsistency using isoCountryCode vs country)
REG-362
    

Author: kbraak@gbif.org
Created: 2013-01-14 16:11:39.292
Updated: 2013-01-14 16:11:39.292
        
All service parameter names now use the lower camel case convention. The http://dev.gbif.org/wiki/display/POR/Webservice+API has been updated.

The only outstanding issue, is to ensure that the Portal web application calls the services uses lower camel case. This issue has been described in POR-460.

The review can now be considered completed, and this issue closed.