Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

First draft of OCR-D Web API #173

Merged
merged 24 commits into from Apr 6, 2022
Merged

First draft of OCR-D Web API #173

merged 24 commits into from Apr 6, 2022

Conversation

kba
Copy link
Member

@kba kba commented Aug 23, 2020

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 )

@EEngl52 EEngl52 added this to In progress in coordinate Sep 3, 2020
@paulpestov paulpestov added this to Ideas in coordinate_all Aug 30, 2021
@paulpestov paulpestov removed this from Ideas in coordinate_all Aug 30, 2021
@paulpestov paulpestov added this to Open in coordinate_all_pr Sep 15, 2021
Copy link
Contributor

@mweidling mweidling left a comment

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

openapi.yml Outdated Show resolved Hide resolved
openapi.yml Outdated Show resolved Hide resolved
openapi.yml Outdated Show resolved Hide resolved
openapi.yml Show resolved Hide resolved
openapi.yml Outdated Show resolved Hide resolved
openapi.yml Outdated Show resolved Hide resolved
openapi.yml Outdated Show resolved Hide resolved
openapi.yml Outdated Show resolved Hide resolved
openapi.yml Show resolved Hide resolved
openapi.yml Show resolved Hide resolved
openapi.yml Outdated Show resolved Hide resolved
openapi.yml Show resolved Hide resolved
openapi.yml Outdated Show resolved Hide resolved
openapi.yml Outdated Show resolved Hide resolved
openapi.yml Outdated Show resolved Hide resolved
openapi.yml Outdated Show resolved Hide resolved
openapi.yml Outdated Show resolved Hide resolved
openapi.yml Outdated Show resolved Hide resolved
openapi.yml Outdated Show resolved Hide resolved
kba and others added 4 commits Mar 4, 2022
Co-authored-by: mweidling <13831557+mweidling@users.noreply.github.com>
Co-authored-by: Konstantin Baierer <kba@users.noreply.github.com>
@mweidling
Copy link
Contributor

mweidling commented Apr 4, 2022

We will omit the JSON-LD part for now.

openapi.yml Outdated Show resolved Hide resolved
openapi.yml Outdated Show resolved Hide resolved
kba and others added 8 commits Apr 4, 2022
Co-authored-by: mweidling <13831557+mweidling@users.noreply.github.com>
Co-authored-by: mweidling <13831557+mweidling@users.noreply.github.com>
Co-authored-by: mweidling <13831557+mweidling@users.noreply.github.com>
Co-authored-by: mweidling <13831557+mweidling@users.noreply.github.com>
@mweidling
Copy link
Contributor

mweidling commented Apr 6, 2022

@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 marked this pull request as ready for review Apr 6, 2022
@kba
Copy link
Member Author

kba commented Apr 6, 2022

@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
Copy link
Contributor

mweidling commented Apr 6, 2022

@kba kba merged commit 5112739 into master Apr 6, 2022
@kba kba deleted the web-api branch Apr 6, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
No open projects
coordinate
  
In progress
Development

Successfully merging this pull request may close these issues.

None yet

2 participants