SORMAS OData service using Apache Olingo

[MartinWahnschaffe]

Situation Description

Internal and external systems often have the need to access the SORMAS data in a query-like manner, e.g. to search for entities with certain values or to limit the returned data to a subset of fields.

Feature Description

OData is an open protocol that does just that using a ReSTful-API. The Apache Olingo library is an OData implementation. For OData v2 it also provides an extension to automatically map entities based on JPA, that we want to use here. Note: There is also an extension for v4 provided by SAP, but it's not clear how well this is working, so we should stick to v2.

See https://olingo.apache.org/doc/odata2/tutorials/CreateWebApp.html and https://www.baeldung.com/olingo

• [ ] Move all entity classes to a new project "sormas-dao". This is necessary, because they will be used by the OData service. Including the whole sormas-backend.jar into it would duplicate the ejbs.
• [ ] Create a new project "sormas-odata"
• [ ] Add authentification as we have in sormas-rest
• [ ] Implement a service based on the Olingo JPA extension
• [ ] Add a new user right "SORMAS_ODATA" that is needed to access the service
• [ ] Also add a new user role "SORMAS_ODATA" that has this right
• [ ] Limit access to GET. For now it should not be possible to manipulate data via PUT, POST, DELETE, etc.

Data security perspective

OData is an OASIS and ISO/IEC standard for accessing data via a ReSTful API. As such, it allows records to be queried and navigated through using standard HTTP calls. The data is returned as either XML or JSON.

It uses the Apache Olingo OData 2.0 Java library with the JPA processor extension. This allows access to all data mapped via JPA - so in the case of SORMAS, the full database.

Examples:

• https://sormas.example.de/sormas-odata/Cases/$count returns the number of all cases.
• https://sormas.example.de/sormas-odata/Cases returns the complete data of all cases, but does not include the data of related entities (e.g. the data of the person).
• https://sormas.example.de/sormas-odata/Cases(123) returns the data of the case with database ID "123".
• https://sormas.example.de/sormas-odata/Cases(123)?$expand=Person also outputs the data of the related person for the case.
• https://sormas.example.de/sormas-odata/Cases(123)?$select=UUID,Diseease outputs the UUID and the disease for the case.

Access to SORMAS OData is only possible with the appropriate authorisation. This means that a user must be created in SORMAS who has the SORMAS OData authorisation.

Important: There is no restriction of the data based on the authenticated user.

Translated with www.DeepL.com/Translator (free version)

[JonasCir]

This is super cool and useful! :)

[tkaefer]

Thanks for picking up my idea. It will be pretty helpful.