API Design

[edeandrea]

This is a parent issue for discussing the API design. We can create subtasks as needed.

Originally posted by @ThomasVitale in #22 (comment)

[ThomasVitale]

From what we discussed, it seems we are aiming for these requirements. @edeandrea @lordofthejars what do you think?

API

• the API should require as little maintenance effort as possible

• the API should be designed in a way that it will be eventually possible to automate its generation

• the API should be resilient to newly added fields/types in newer versions of Docling

• the API should be resilient to newly added enum values in newer versions of Docling

• the API should be agnostic with respect to specific JSON Parsing library implementations

• the API should be agnostic with respect to specific validation library implementations

• the API should be usable by libraries/frameworks together with Jackson 2

• the API should be usable by libraries/frameworks together with Jackson 3

• the API can adopt Jackson annotations as long as the dependency is not required in the published artefact

• the API can adopt Jakarta Validation annotations as long as the dependency is not required in the published artefact.

Client

• the Client should work as a reference implementation and can be based on the JDK HttpClient and Jackson
• it should be possible for libraries/framework to provide a custom implementation using the HTTP Client and JSON Parsing libraries of their choice.

[edeandrea]

100% agree with all of the above

[edeandrea]

If we were to prioritize these, this would be my vote:

API

1. the API should require as little maintenance effort as possible
2. the API should be resilient to newly added fields/types in newer versions of Docling
3. the API should be resilient to newly added enum values in newer versions of Docling
4. the API should be designed in a way that it will be eventually possible to automate its generation
5. the API should be agnostic with respect to specific JSON Parsing library implementations (i.e. Jackson 2/3, Gson, Json-B, etc)
   • This also means that the API can adopt Jackson annotations as long as the dependency is not required in the published artifact
6. the API should be agnostic with respect to specific validation library implementations
   • This also means that the API can adopt Jakarta Validation annotations as long as the dependency is not required in the published artifact.

Client

1. the Client should work as a reference implementation and can be based on the JDK HttpClient and Jackson
2. it should be possible for libraries/framework to provide a custom implementation using the HTTP Client and JSON Parsing libraries of their choice.

[lordofthejars]

LGTM