Skip to content

Functionality and Requirements

Jump to bottom
Guy Davenport edited this page Nov 20, 2025 · 11 revisions

Overview

The current IPK Validator contains a wide variety of features that clutters up the UI and makes it difficult to maintain. It also utilizes older ThymeLeaf UI elements that are difficult to modify or modernize. An attempt was made to update the code base, which included a new ThymeLeaf interface, Angular front end and Command line interface (CLI).

The BRAVA-Tools API is being created as a way to simplify what is actually required for a basic, simple validation process.

Original Loose Requirements

Incorporate brava-core from the IPK-Validator refactor branch, the use-caseinator BrApp Use Case Checker, and the logic from the analyse tool from BrAPI-schema-tools into one API (or CLI) that can be used to validate BrAPI-compatible servers and their endpoints.

Use this new API to create a new, modern web app that can be used easily to validate BrAPI-compatible servers.

This web app should have the following features:

  • Validate servers given an endpoint, version, and authentication, if provided
  • Determine if use cases for BrApps have the required endpoints implemented (and validated?) for a given server
  • Create new use cases for BrApps and test them, provide a pipeline to facilitate adding these use cases to the use-caseinator library
  • Have an easy way to switch between these different features, think tools in a tool belt

We've gotten decently far with these loose requirements, but at this point it is time to brainstorm and spec out the features and functionality we expect from both the API and the web app.

Proposed Functionality

The new version of BRAVA should be modular allowing users to integrate only the part of the code base required for their use case. The modules would be:

  • Core - A Java library that will send RESTful requests to a server and check for compliance to the BrAPI Specification.
  • BRAVA - A Java library that will test all the Endpoints defined in a BrAPI Specification on a given server.
  • Use Case Checker (Use-caseinator) - A Java library that will test only those Endpoints on a given server that are required for a specific Use Case.
  • Web application - A spring web-application that provide endpoints to call the BRAVA and Use-caseinator
  • CLI - A command line application (CLI) that calls the Validator and Use-caseinator libraries
  • BRAVA Tools Website - An Angular or Vue application that use the Web application - Not part of this repo See BRAVA Tools Website

Note that full Proposed Functionality does not take into account the priority of the work and if the full functionality will actually be implemented. However, it provides context for the development and the road map (see below).

Core

The Core API will consist of a Validator class that will send an HTTP Request to a specific endpoint and validate the Response.

Validator

The Validator will take in it's construction the following:

  • The root BrAPI server URL - Mandatory
  • The OpenAPI specification as a string or URI to the specification, which could be a URL or file. - Mandatory
  • The JSON Schemas - URI to the schemas, which could be a a Map of Schema objects, an URL to directory or a directory file system path. - Optional
  • An options POJO - If not provided a default Options object would be created. - Optional
  • An AuthorizationProvider - No Authorization by default. - Optional

The Validator 'validate' method would take as an input the following

  • The endpoint, that will be suffixed to the root URL - Mandatory. This will include any path parameters
  • The HTTP Method - GET, POST, PUT or DELETE - Mandatory
  • An request object - Optional - The input will be treated differently depending on the HTTP method
    • GET - The request object would be a JSON object, Map or POJO. In any case the object will be converted to key value pairs and appended to the endpoint in the full URL as parameters. If any of the values are non-primitive or non-string, an exception will be returned in the response. GET endpoints can be one of three types which will be treated separately by the Validator
      • Get Single Entity - Returns a single entity by DbId
      • Simple List Query - Returns a optionally filtered list of entities.
      • Paged List Query - Returns a filtered paged list of entities.
    • POST/PUT- The request object would be a JSON object, Map or POJO. In any case the object will be converted to a JSON object and submitted in the body of the HTTP Request
      • POST is used either to Create a new entity or entities, or to perform a Search. These two type of Endpoints will be treated separately by the Validator. A synchronous Search will return a result once available, whereas an asynchronous Search will return a searchDbId immediately. This searchDbId can be used to obtain the result when available.
      • PUT is used to Update an entity or entities
    • DELETE - The request object should be null. If not an exception will be returned in the response
  • An response object - An optional JSON object that defines the expected response - Mandatory in the case of level 3 validation

The Validator 'validate' method would return a ValidateResponse object, which can be used by the upstream code.

The Validator will perform several validation checks depending on the required maximum level that is defined in the Options. The level checks are accumulative, so for all the lower level checks are done in order of level before the maximum level is reached. The levels of validation that will be performed are:

Level 1 - Record the HTTP Status, and response time. This is lower level used by the Use-caseinator to check if the Endpoint is present. Note that a response code of 404 is a valid response in the case of Single Entity GET Endpoints. It indicates that a entity instance (object) was not found. The Validator will need to differentiate between this case and the absence of the endpoint. If the HTTP Status is not in the list of possible status defined in the specification of the endpoint, the response will contain a validation error.

Level 2 - Validate the response against the endpoint specification. Ensure that the structure of the response is consistent with the OpenAPI specification. If the Validator has access to the JSON schema, the returned JSON will be validated against this schema.

Level 3 - Compare the content of the response with the expected content.

Validation Options

The Use-caseinator Options are

Option Description Type Default
Maximum Level Can be 1, 2 or 3, see above. Integer 1
Page size The size of page to be used in paged Endpoints Integer null
Page number The number of pages to be validated in paged Endpoints Integer 2

Validation Response

HTTP Client

The standard HTTP Client that is available from Java 11 is sufficient for the task, there is no need to use a 3rd party client

Authentication and Authorization

Some BrAPI servers require Authorization though the use of a HTTP Header. AuthorizationProvider will be used by Validator class, which will provide the Authorization on request. Some Authentication methods require a token that can expire during the long process of validating many endpoints. For this reason the AuthorizationProvider will provide the Authorization header just in time and handle any requests to Authentication servers, SSO, refreshing of tokens etc. The Core API will provide the AuthorizationProvider implementations, although a developer may wish to provide their own implementations

  • No Authorization - No header will be provider for cases when the server is not secured
  • Basic Authorization - A username and password is encoded and provided in the header
  • Bearer Authorization - A Bearer token is provided in the header
    • The Provider can obtain the token directly from the calling code or via OAuth2 call to OAuth2 server, that will also handle requesting, refreshing, caching of the token in a local secured directory using a username and password, or client id and secret.

Technical Specification

The Core API will make use of

  • Java 21 or 25 which are both LTS
  • Gradle 8.4 Java 21 or 9.1.0 if Java 25 is used
  • Lombok for creating POJOs and builder classes
  • Logging using SLF4J, allowing users to provide their own logging implementation.
  • Jackson JSON Library
  • JSON comparison library - TBD
  • JSON Schema library - TBD
  • JSON Schema Validation library - TBD

BrAPI Server Validator (BRAVA)

BRAVA will take in it's construction the following:

  • The root BrAPI server URL - Mandatory
  • The OpenAPI specification as a string or URI to the specification, which could be a URL or file. - Mandatory
  • The JSON Schemas - URI to the schemas, which could be a a Map of Schema objects, an URL to directory or a directory file system path. - Optional
  • An options POJO - If not provided a default Options object would be created. - Optional
  • An AuthorizationProvider - No Authorization by default. - Optional

Note these inputs may be separate arguments, wrapped in a POJO and/or read from a file. TBD

The BRAVA has two modes, synchronous and asynchronous

In synchronous mode it iterates through all the Endpoints one at a time in the provided BrAPI Specification depending on the options and calls the 'validate' method. Returns a BRAVAResponse that contains a map of the individual ValidateResponses.

In asynchronous mode the same Endpoints are validated as per the synchronous mode, the endpoints are called in batches and it returns asynchronous AsyncBRAVAResponse, that can be queried to see if a individual ValidateResponse is available.

In either case the order in which the Endpoints are called will be important if Create, Update or Delete Endpoint are being validated.

  • Create only - The Create endpoint is called and the Delete endpoint later called to remove the created endpoint. Validation only occurs on the Create endpoint.
  • Update only - The Create endpoint is called first, then the Update endpoint and the Delete endpoint later called to remove the created endpoint. Validation only occurs on the Update endpoint.
  • Delete only - The Create endpoint is called first, then the Delete endpoint is called. Validation only occurs on the Delete endpoint.
  • Create and Update - The Create endpoint is called first, then the Update endpoint and the Delete endpoint later called to remove the created endpoint. Validation only occurs on the Create and Update endpoints.
  • Create and Delete - The Create endpoint is called first, then the Delete endpoint is called. Validation only occurs on the Create and Delete endpoints.
  • Update and Delete - The Create endpoint is called first, then the Update endpoint and finally the Delete endpoint is called. Validation only occurs on the Update and Delete endpoints.
  • Update and Delete - The Create endpoint is called first, then the Update endpoint and finally the Delete endpoint is called. Validation occurs on the Create, Update and Delete endpoints.

BRAVA Options

The BRAVA Options are

Option Description Type Default
Maximum Level Can be 1, 2 or 3, see above. Integer 1
Server Info only Validate only those Endpoints defined in Server Info Boolean False
Get Single Entity Validate Get Single Entity Endpoints Boolean True
Simple List Query Validate Simple List Query Endpoints Boolean True
Paged List Query Validate Paged List Query Endpoints Boolean True
Search Validate Search Endpoints Boolean True
Table Validate Table Endpoints Boolean True
Create Validate Create Endpoints Boolean False
Delete Validate Delete Endpoints Boolean False

Use Case Checker (Use-caseinator)

BRAVA will take in it's construction the following:

  • The root BrAPI server URL - Mandatory
  • The OpenAPI specification as a string or URI to the specification, which could be a URL or file. - Mandatory
  • A list of endpoints that need to be checked - Mandatory
  • The JSON Schemas - URI to the schemas, which could be a a Map of Schema objects, an URL to directory or a directory file system path. - Optional
  • An options POJO - If not provided a default Options object would be created. - Optional
  • An AuthorizationProvider - No Authorization by default. - Optional

Note these inputs may be separate arguments, wrapped in a POJO and/or read from a file. TBD

The Use Case Checker Response is a general message that provides a check overall status

  • fully implemented
  • partially implemented
  • not implemented

The Use Case Checker Response also has a count of what Endpoint are implemented and which are not. It also contains a map of the individual ValidateResponses.

Use-caseinator Options

The are Options are

Option Description Type Default
Server Info only Validate only those Endpoints defined in Server Info Boolean False

Technical Specification

See Core Technical Specification

Web application

A spring web-application that provide endpoints to call the Validator and Use-caseinator

Technical Specification

See Core Technical Specification

Additional dependencies

  • Spring Boot 3.5.7

Command Line Interface

A Command Line Interface calls the Validator and Use-caseinator

Technical Specification

See Core Technical Specification

Additional dependencies

  • Picocli 4.7.7 API)

Proposed Roadmap

  1. Core Validator level 1, including Basic Authentication
    • In scope
      • Get Single Entity
      • Simple List Query
      • Paged List Query
      • Search
    • Out of scope
      • Create
      • Update
      • Delete
  2. Move Use-caseinator to use Core Validator level 1
  3. Start development of Spring Web Application
    • This will continuously updated as the Use-caseinator and BRAVA is developed
  4. Start development of Web App
    • This will continuously updated as the Spring Web Application is developed
  5. Core Validator level 2
    • In scope
      • Get Single Entity
      • Simple List Query
      • Paged List Query
      • Search
    • Out of scope
      • Create
      • Update
      • Delete
  6. Start development of BRAVA using Core Validator level 2
  7. Start development of CLI
    • This will continuously updated as the Use-caseinator and BRAVA is developed
  8. Core Validator level 3
    • In scope
      • Get Single Entity
      • Simple List Query
      • Paged List Query
      • Search
    • Out of scope
      • Create
      • Update
      • Delete
  9. Core Validator level 1-3
    • In scope
      • Create
      • Update
      • Delete

Development Team

Module Lead Developers Tester
Core TBD Guy, Jason, Peter? ?
Use-caseinator Jason Guy, Peter? ?
BRAVA ? Guy, Jason, Peter? ?
Spring Guy Jason, Peter? ?
CLI Guy Jason, Peter? ?
Web app Jason Guy, Peter? ?

IPK Validator Repo

The existing IPK Validator Repo will be retired after all functionality exists in the new code base

Clone this wiki locally