Schematic overview

Risks and benefits when implementing

Custom implementation

When a custom implementation is created please keep in mind that Blueriq upgrades may lead to changes in the persistence API, which should be implemented in the custom implementation to avoid loss of functionality (e.g. Blueriq plugins who call the API). Where possible we will try to be backwards compatible, but if not possible it may be that the impact of an upgrade is larger then usually.

Different programming language

When the default programming language within an organization is different from Java it may not be desirable to obtain and maintain Java knowledge. This could be a reason to implement a complete custom Persistence API implementation in the desired programming language. Besides the OLingo (Java) library which is used by Blueriq, libraries are available for at least .Net, Javascript, C++ and Python.

• Benefit
  • Free to choose a programming language
• Risks
  • Knowledge of OData is needed.
  • A specific OData implementation is needed that understands the URL's generated by Blueriq. The URL's generated by the runtime are specific for Blueriq due to the generic behavior of the product.

Different database

Within many enterprise organisations a certain database type is preferred above others. Please see Platform Support for more details on our supported database types. If the preferred database type of a customer is different and the costs of setting up and maintaining or the license costs of one of the supported types are too high a custom implementation can be made based on the Blueriq API that reuses the Blueriq API and OData\OLingo implementation and translation modules. This means that the Blueriq libraries are used to translate the OData HTTP requests to API calls and predefined expression trees. The API calls and the translation of the expression trees to custom SQL queries need to be implemented.

• Benefits
  
  • Limited knowledge of OData is needed.
  • Not all OData functionality has to be reimplemented.
  • Custom implementation is closer to the default Blueriq implementation. This has the advantage that the impact of changes in the Persistence API is smaller.
• Risks
  
  • No free choice of programming language.

Different database scheme

It may be desirable to store the data in another format than the default Aggregates with custom metadata fields. For example data should be stored as relational data instead of the current approach Aggregates. In this scenario a custom implementation may reuse of the Blueriq API and OData\OLingo implementation and translation modules. This means that the Blueriq libraries are used to translate the OData Http-requests to API-calls and predefined expression trees. The API calls have to be implemented, the expression trees have to be translated to custom SQL queries and mapping to the custom scheme has to be created and maintained.

• Benefits
  

  • Limited knowledge of OData is needed.

  • Not all OData functionality has to be reimplemented.

  • Custom implementation is closer to the default Blueriq implementation.

• Risks
  
  • No free choice of programming language.
  • Flexibility loss due to that model changes that should be persistent lead to changes in the database as well

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 (depending 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 : 100 milliseconds
• GET by key : 100 milliseconds
• GET by criteria : 1000 milliseconds*
• PUT : 100 milliseconds
• DELETE : 100 milliseconds

*Complex filter operations on large data sets will exceed this

Minimum number of concurrent requests

A custom implementation should be able to handle at least 10 concurrent HTTP requests, 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 data size is mainly determined by the aggregate model as defined in Encore, there are no explicit data size requirements on the custom service side.