How to create your own implementation of the persistence API [Editor]

Schematic overview

Requirements and limitations

OData V4 service schema

Like every OData V4 compliant service a custom implementation must also publish an OData V4 service schema. A custom implementation must use the same schema as the default Blueriq persistence service implementation. When using the default deployment (from the Blueriq installer), the schema can be obtained through the URL 'http://localhost:10099/customerdata/api/v1/$metadata'

HTTP response codes

GET request:

• 200 Ok: with as message body the requested Aggregate. (read)
• 404 Not Found. When aggregate with specific id and version cannot be found  (BlueriqDataNotFoundException).
• 500 Internal Server Error. On a BlueriqDataException (including BlueriqDataAccessException and BlueriqQueryTranslationException)

POST request:

• 201 Created: with as message body the created Aggregate. (default response)
• 204 No Content: with no message body. If the request included a return Prefer header with a value of return=minimal
• 400 Bad Request. When a BlueriqDataIntegrityViolationException is thrown from the repository.
• 500 Internal Server Error. On a BlueriqDataException (including BlueriqDataAccessException and BlueriqQueryTranslationException)

PUT request:

• 200 Ok: with as message body the updated Aggregate. (update)
• 201 Created: with as message body the created Aggregate. (upsert/create)
• 204 No Content: with no message body. If the request included a return Prefer header with a value of return=minimal. (update+upsert/create)
• 400 Bad Request. When a BlueriqDataIntegrityViolationException is thrown from the repository.
• 404 Not Found. When the (Aggregate)Id cannot be found in the database or the version cannot be found in the database with the If-Match header send in the request (BlueriqDataNotFoundException).
• 500 Internal Server Error. On a BlueriqDataException (including BlueriqDataAccessException and BlueriqQueryTranslationException)

PATCH request:

• 501 Not Implemented. The patch request is not supported and will always return a 501 Not Implemented.

DELETE request:

• 204 No Content: with no message body. On successful completion of the delete. 
• 400 Bad Request. When a BlueriqDataIntegrityViolationException is thrown from the repository.
• 404 Not Found. When the (Aggregate)Id cannot be found in the database or the version cannot be found in the database if both are specified in the request (BlueriqDataNotFoundException).
• 500 Internal Server Error. On a BlueriqDataException (including BlueriqDataAccessException and BlueriqQueryTranslationException)

Logging requirements

Parts of the desired information is logged by the Blueriq runtime, this includes:

• Conversion errors from Blueriq profile instance to aggregate
• Adding of returned aggregate results to Blueriq profile
• AQ_Aggregate service call parameters

For a custom implementation there are currently no explicit logging requirements, things to consider for logging:

• HTTP requests and responses
• OData errors (dependening on the implementation variant)
• Database errors
• Service call ID to uniquely identify requests

Transaction boundaries

Service operations for a custom implementation should be transactional. This means that in case of failure the database should be rolled back to the state before the operation started. Transactions are not expected to span multiple service operations.

Maximum response times

Service operations for a custom implementation should respond in a timely fashion, the absolute maximum allowed response times are:

• POST : 500 milliseconds
• GET by key : 500 milliseconds
• GET all : 20 seconds (if this is exceeded use filtering and/or paging to limit the response time)
• PUT : 500 milliseconds
• DELETE : 500 milliseconds

Minimum number of concurrent users

A custom implementation should support at least 10 concurrent users regardless of the service operation that is performed

Maximum data size

Service operation responses for a custom implementation should not be too big, the maximum allowed response sizes are:

• POST : 100 KB
• GET by key : 100 KB
• GET all : 10 MB (if this is exceeded use filtering and/or paging to limit the response size)
• PUT : 100 KB
• DELETE : 1 KB