From d705db6a9377104a39935038e0212549e917da1e Mon Sep 17 00:00:00 2001 From: Jan Kanis Date: Mon, 13 Jun 2016 11:33:03 +0200 Subject: [PATCH 1/2] Don't include the database id when exporting patients The internal database id should not be used outside of the Transmart server, the trial id (inTrialId) should be used for that. The database id is not useful anyway since it is not exported in other places so it cannot be correlated. The accompanying update in RInterface is in the patient_sets branch. --- .../rest/marshallers/PatientSerializationHelper.groovy | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/groovy/org/transmartproject/rest/marshallers/PatientSerializationHelper.groovy b/src/groovy/org/transmartproject/rest/marshallers/PatientSerializationHelper.groovy index c4c0bde..f6a4406 100644 --- a/src/groovy/org/transmartproject/rest/marshallers/PatientSerializationHelper.groovy +++ b/src/groovy/org/transmartproject/rest/marshallers/PatientSerializationHelper.groovy @@ -51,7 +51,7 @@ class PatientSerializationHelper extends AbstractHalOrJsonSerializationHelper convertToMap(Patient patient) { - Map result = getPropertySubsetForSuperType(patient, Patient, ['assays', 'sex'] as Set) + Map 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 } From ec07437264431889bfe9ad11f9155652dc5e01df Mon Sep 17 00:00:00 2001 From: Jan Kanis Date: Mon, 13 Jun 2016 14:05:26 +0200 Subject: [PATCH 2/2] create /transmart-rest-api-version rest api needs a version number so that clients can fail gracefully if they are not compatible. There is at the moment no intention to have the server or R client support multiple versions at the same time. --- CHANGES | 32 +++++++++++++++++++ grails-app/conf/RestApiUrlMappings.groovy | 2 ++ .../rest/ApiVersionController.groovy | 31 ++++++++++++++++++ 3 files changed, 65 insertions(+) create mode 100644 CHANGES create mode 100644 grails-app/controllers/org/transmartproject/rest/ApiVersionController.groovy diff --git a/CHANGES b/CHANGES new file mode 100644 index 0000000..8d2e2ce --- /dev/null +++ b/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. diff --git a/grails-app/conf/RestApiUrlMappings.groovy b/grails-app/conf/RestApiUrlMappings.groovy index 9e97fcd..91d828b 100644 --- a/grails-app/conf/RestApiUrlMappings.groovy +++ b/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') { diff --git a/grails-app/controllers/org/transmartproject/rest/ApiVersionController.groovy b/grails-app/controllers/org/transmartproject/rest/ApiVersionController.groovy new file mode 100644 index 0000000..9bd320c --- /dev/null +++ b/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" + } + +}