First draft of OCR-D Web API

[kba]

Here's an initial draft of the HTTP API for OCR-D processing servers. Much more still needs to be fleshed out, obviously. But since this subject is of interest for many in OCR-D, I want to share early so we can agree on the direction we should take with the API.

The API is defined as OpenAPI 3 YAML. Resources follow the JSON-LD convention of assigning the resource URL as @id attribute. Media types are described in the preamble, emphasis is placed on a consistent data model. The requests are grouped by tag, so that implementers can choose whether to implement specific areas (e.g. the "OCR-D processing API v1").

You can explore the API in a GUI on SwaggerHub.

TODO:

• Handling parameters (i.e. ocrd processor parameters)
• Document JSON-LD convention for @id (see Add JSON-LD to WebAPI #194)
• Consider distributed services and how they interact to retrieve data in a sensible and low-bandwidth way (this is non-normative and could be covered by a best practice section on the website) (see WebAPI: Best practices #195)
• Mechanism for actively signalling events (Web Hooks, Web Sockers, AQMP...) (this will be part of a reference implementation and is not part of the API) (see WebAPI: Event notifications #196 )

[mweidling]

Mainly language and style stuff, in-depth thoughts will follow

[mweidling]

We will omit the JSON-LD part for now.

[mweidling]

@kba Since all discussions are resolved, are we ready to merge this? Or do we have any dependencies/things we have to do before?

[kba]

@kba Since all discussions are resolved, are we ready to merge this? Or do we have any dependencies/things we have to do before?

🚀🚢 No I think we can release an initial 0.x version and potentially adapt with feedback before a 1.0.0 release in a few weeks.

[mweidling]

✨