Don't include patient database id in rest api output && implement rest api version number

CHANGES

@@ -0,0 +1,32 @@
+The version number follows semantic versioning: minor number updates indicate backward compatible changes, major
+number updates indicate backward-incompatible versions. In that case clients will usually need to be updated.
+Add any changes that change the endpoints or the data they return here. 
+
+INCREMENT THE VERSION NUMBER IF YOU RELEASE A CHANGED VERSION! Then clients can fail gracefully instead of raising some exception.
+
+
+3.0
+===
+
+The first version with a version number.
+
+added: 
+	- /patient_sets endpoint
+
+changed:
+	- SubjectController no longer returns the database id of patients. The database id should not be used outside of Transmart, and was not 
+	useful anyway since it was not exposed anywhere else. Use the inTrialId instead. This change breaks old R clients since they use the 'id' 
+	column as the name in the patients data frame.
+
+
+earlier versions
+================
+
+Earlier versions do not have a version number.
+
+There are two known incompatible changes in the past:
+
+- /oauth/verify got changed to /oauth/inspectToken for checking if a token is still valid. The latter 
+  returns different more useful information, and the former no longer works for this purpose.
+- A new version of the oauth plugin no longer accepts GET requests for logging in, which the R client uses.
+  The R client needs to change to using POST requests.

grails-app/conf/RestApiUrlMappings.groovy

@@ -28,6 +28,8 @@ class RestApiUrlMappings {
     // grails url-mappings-report can come handy here...
 
     static mappings = {
+        '/transmart-rest-api-version'(controller: 'apiVersion', method: 'GET', includes: ['index'])
+
         '/studies'(controller: 'study', method: 'GET', resources: 'study', includes: ['index', 'show'])
 
         '/studies'(resources: 'study', method: 'GET') {

grails-app/controllers/org/transmartproject/rest/ApiVersionController.groovy

@@ -0,0 +1,31 @@
+package org.transmartproject.rest
+
+/**
+ * This controller exposes the version of the api, so that clients can see if they support the current api version.
+ * The version number follows semantic versioning: minor number updates indicate backward compatible changes, major
+ * number updates indicate backward-incompatible versions. In that case clients will usually need to be updated.
+ * Patch levels are not exposed here since clients don't need to know it.
+ *
+ * If you add a new endpoint to rest-api or you add information to the exported data, you MUST increment the minor
+ * version.
+ *
+ * If you change any functionality in a way that could break clients (e.g. remove endpoints, change data formats or
+ * fields, etc), you MUST increment the major number.
+ *
+ * In both cases you MUST document the changes in the CHANGES file.
+ *
+ * This version number is purely for api compatibility, it is not related to the transmart release version number.
+ *
+ * This endpoint was introduced with version 3.0, previous versions do not have a /transmart-rest-api-version
+ * endpoint at all.
+ */
+class ApiVersionController {
+
+    static responseFormats = ['json', 'hal']
+
+    // See CHANGES for what changes were done in which version number
+    def index() {
+        render "3.0\n"
+    }
+
+}

src/groovy/org/transmartproject/rest/marshallers/PatientSerializationHelper.groovy

@@ -51,7 +51,7 @@ class PatientSerializationHelper extends AbstractHalOrJsonSerializationHelper<Pa
 
     @Override
     Map<String, Object> convertToMap(Patient patient) {
-        Map<String, Object> result = getPropertySubsetForSuperType(patient, Patient, ['assays', 'sex'] as Set)
+        Map<String, Object> result = getPropertySubsetForSuperType(patient, Patient, ['id', 'assays', 'sex'] as Set)
         result.put('sex', patient.sex.name()) //sex has to be manually converted (no support for enums)
         result
     }