Issue 11945

Review webservice query parameter naming across all webservices

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 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

Comment: first list inconsistencies
Created: 2012-11-21 12:42:00.949
Updated: 2012-11-21 12:42:00.949

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)

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. 

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-361 (note added about potential inconsistency using isoCountryCode vs country)

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 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.