Merge branch 'stable' into feature-DATAAPI-37_support_custom_endpoints

Author: DominicWatson

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## v3.7.1
+
+* Always respect returned value from custom field renderer
+
+## v3.7.0
+
+* new options to skip data validation and customize the response type on inserts/updates, also 4 new interception points added
+
 ## v3.6.0
 
 * Added a UI to show records in the DATA API change queue per subscribed API client

README.md

@@ -52,6 +52,10 @@ Additional _optional_ annotation options at the _object_ level are:
 * `dataApiFilterFields`: Fields to allow as simple filters for paginated GET requests (defaults to foreign keys, boolean and enum fields)
 * `dataApiAllowIdInsert`: Whether or not to allow the ID field to be set during a POST operation to create a new record
 * `dataApiQueueRelevantFields`: Fields that are relevant to trigger a record update to be queued. If not used, then any data change will be queued. If used then only the specified fields will be examined and in case of atomic-changes for the queue only the relevant field changes will be included in the queue item. Inserts and deletes are always queued, only during updates this annotation is evaluated.
+* `dataApiSkipValidationOnInsert`: Whether or not to skip data validation when inserting new records (defaults to `false`)
+* `dataApiSkipValidationOnUpdate`: Whether or not to skip data validation when updating records (defaults to `false`)
+* `dataApiResponseTypeOnInsert`: Could be `record`, `idonly` or `empty` (defaults to `record`)
+* `dataApiResponseTypeOnUpdate`: Could be `record`, `idonly` or `empty` (defaults to `record`)
 
 ### Property annotations
 
@@ -191,7 +195,7 @@ Fires before inserting data through the API. Receives the following keys in the
 * `insertDataArgs`: Arguments that will be passed to the `insertData()` call
 * `entity`: Name of the entity being operated on
 * `record`: The data that will be inserted (struct)
-
+* `responseType`: Whether the API response should be `empty`, contain the full `record` or `idonly`. Defaults to the API or object definition (or if not defined `record`), but can be overwritten here.
 
 ### `postDataApiInsertData`
 
@@ -201,7 +205,7 @@ Fires after inserting data through the API. Receives the following keys in the `
 * `entity`: Name of the entity being operated on
 * `record`: The data that will be inserted (struct)
 * `newId`: Newly created record ID
-
+* `responseType`: Whether the API response should be `empty`, contain the full `record` or `idonly`. Defaults to the API or object definition (or if not defined `record`), but can be overwritten here.
 
 ### `preDataApiUpdateData`
 
@@ -211,6 +215,7 @@ Fires before updating data through the API. Receives the following keys in the `
 * `entity`: Name of the entity being operated on
 * `recordId`: ID of the record to be updated
 * `data`: The data that will be inserted (struct)
+* `responseType`: Whether the API response should be `empty`, contain the full `record` or `idonly`. Defaults to the API or object definition (or if not defined `record`), but can be overwritten here.
 
 ### `postDataApiUpdateData`
 
@@ -220,6 +225,7 @@ Fires after updating data through the API. Receives the following keys in the `i
 * `entity`: Name of the entity being operated on
 * `recordId`: ID of the record to be updated
 * `data`: The data that will be inserted (struct)
+* `responseType`: Whether the API response should be `empty`, contain the full `record` or `idonly`. Defaults to the API or object definition (or if not defined `record`), but can be overwritten here.
 
 ### `preDataApiDeleteData`
 
@@ -237,6 +243,39 @@ Fires after deleting data through the API. Receives the following keys in the `i
 * `entity`: Name of the entity being operated on
 * `recordId`: ID of the record to be deleted
 
+### `onDataApiUpdateRecordDataValidation`
+
+Fires before starting data validation on updates. Receives the following keys in the `interceptData`:
+
+* `entity`: Name of the entity being operated on
+* `data`: The data to be validated
+* `skipValidation`: Whether the whole validation should be skipped. Defaults to the API or object definition, but can be overwritte here.
+
+### `onDataApiInsertRecordDataValidation`
+
+Fires before starting data validation on inserts. Receives the following keys in the `interceptData`:
+
+* `entity`: Name of the entity being operated on
+* `data`: The data to be validated
+* `skipValidation`: Whether the whole validation should be skipped. Defaults to the API or object definition, but can be overwritte here.
+
+### `preDataApiBatchUpdateRecords`
+
+Fires before batch updating multiple records. Receives the following keys in the `interceptData`:
+
+* `entity`: Name of the entity being operated on
+* `records`: Array of record data to be batch updated
+* `responseType`: Whether the API response should be `empty`, contain the full `record` or `idonly`. Defaults to the API or object definition (or if not defined `record`), but can be overwritten here.
+
+### `postDataApiBatchUpdateRecords`
+
+Fires after multiple records have been batch updated. Receives the following keys in the `interceptData`:
+
+* `entity`: Name of the entity being operated on
+* `records`: Array of record data to be batch updated
+* `responseType`: Whether the API response should be `empty`, contain the full `record` or `idonly`. Defaults to the API or object definition (or if not defined `record`), but can be overwritten here.
+* `updated`: Array of the full record data that was updated (or empty array in case skipRecordResponse=true was already set in `preDataApiBatchUpdateRecords`)
+
 ## Data Change Queue(s)
 
 By default, they system enables a queue feature: `settings.features.dataApiQueue`. When enabled, API users can be subscribed, through the admin UI, to listen for data changes to all, or a number, of entities in the system.

config/Config.cfc

@@ -27,7 +27,13 @@ component {
 			, description  = "Generic Preside REST API for external systems to interact with Preside data"
 			, configHandler = "dataApiManager"
 			, dataApiQueues = { default={ pageSize=1, name="", atomicChanges=false } }
-			, dataApiDefaults = { allowIdInsert=false }
+			, dataApiDefaults = {
+				  allowIdInsert          = false
+				, skipValidationOnInsert = false
+				, skipValidationOnUpdate = false
+				, responseTypeOnInsert   = "record" // "empty", "idonly" or "record" (default)
+				, responseTypeOnUpdate   = "record" // "empty", "idonly" or "record" (default)
+			}
 		};
 		settings.rest.apis[ "/data/v1/docs" ] = {
 			  description     = "Documentation for REST APIs (no authentication required)"
@@ -57,6 +63,10 @@ component {
 			, "postDataApiSelectData"
 			, "preValidateUpsertData"
 			, "postValidateUpsertData"
+			, "onDataApiUpdateRecordDataValidation"
+			, "onDataApiInsertRecordDataValidation"
+			, "preDataApiBatchUpdateRecords"
+			, "postDataApiBatchUpdateRecords"
 		];
 		conf.interceptorSettings.customInterceptionPoints.append( conf.settings.dataApiInterceptionPoints, true );
 	}

handlers/rest-apis/data/v1/SingleRecord.cfc

@@ -70,21 +70,23 @@ component {
 			return;
 		}
 
-
 		var updated = dataApiService.updateSingleRecord(
-			  entity   = entity
-			, recordId = recordId
-			, data     = validationData
+			  entity         = entity
+			, recordId       = recordId
+			, data           = validationData
+			, returnResponse = true
 		);
 
-		if ( updated ) {
-			get( argumentCollection=arguments );
-		} else {
+		if ( IsNumeric( updated ) && updated == 0 ) {
 			restResponse.setError(
 				  errorCode = 404
 				, title     = "Not found"
 				, message   = "No [#arguments.entity#] record was found with ID [#arguments.recordId#]"
 			);
+		} else if ( IsStruct( updated ) || IsArray( updated ) ) { // updated and configured to either return the full record or the id only (in an array)
+			restResponse.setData( updated );
+		} else { // updated but configured to return an empty response
+			restResponse.noData();
 		}
 	}
 

handlers/rest-apis/data/v1/WholeEntity.cfc

@@ -85,6 +85,7 @@ component {
 			, data          = body
 			, ignoreMissing = false
 		);
+
 		if ( IsArray( body ) ) {
 			if ( !validationResult.validated ) {
 				restResponse.setError(
@@ -110,7 +111,11 @@ component {
 			, records = IsArray( body ) ? body : [ body ]
 		);
 
-		restResponse.setData( created );
+		if ( IsArray( created ) ) {
+			restResponse.setData( created );
+		} else {
+			restResponse.noData();
+		}
 	}
 
 	private void function put( required string entity ) {
@@ -160,7 +165,10 @@ component {
 			, records = body
 		);
 
-		restResponse.setData( updated );
+		if ( IsArray( updated ) ) {
+			restResponse.setData( updated );
+		} else {
+			restResponse.noData();
+		}
 	}
-
 }

i18n/dataapi.properties

@@ -82,19 +82,24 @@ operation.get.by.id.params.recordId=ID of the **{1}** record that you wish to fe
 
 operation.put.description=Used to batch update **{1}** records.
 operation.put.200.description=Array of updated **{1}** records.
+operation.put.200.description.idonly=Array of updated **{1}** records IDs.
+operation.put.200.description.empty=Empty
 operation.put.422.description=Data validation failure. Returned when one or more entities failed validation. No records will have been updated.
 operation.put.body.description=Array of **{1}** objects to update. Missing fields per item will be ignored and only fields given will be updated.
 
 operation.put.by.id.description=Used to update an individual **{1}** record by ID.
 operation.put.by.id.200.description=Updated **{1}** record object
+operation.put.by.id.200.description.idonly=ID of the updated **{1}** record object
+operation.put.by.id.200.description.empty=Empty
 operation.put.by.id.404.description=No record found for the given ID
 operation.put.by.id.422.description=Data validation failure. Returned when one or more fields have failed validation.
 operation.put.by.id.params.recordId=ID of the **{1}** record that you wish to update.
 operation.put.by.id.body.description=**{1}** object with fields to update. Missing fields will be ignored.
 
-
 operation.post.description=Used to create **{1}** records.
 operation.post.200.description=Array of created **{1}** records.
+operation.post.200.description.idonly=Array of created **{1}** record IDs.
+operation.post.200.description.empty=Empty
 operation.post.422.description=Data validation failure. Returned when one or more entities failed validation. No records will have been created.
 operation.post.body.description=Array of **{1}** objects to create.