Web api

[tdoan2010]

This is my first attempt for the Web API documentation. Comments are welcome.

[bertsky]

Mostly formulations, but some issues too.

[tdoan2010]

What if the server in question does not use queues, but directly schedules local CLI calls or distributed Processor REST calls?

That's a valid argument for having the callback feature. I will update the spec with this.

[tdoan2010]

@bertsky could you resolve those conversations which are "done"? 😃 I know that it's still missing a section to describe the standalone REST processors, but I'll add it later, since I don't want to make this PR bigger (it's already big... 😅 ).

[bertsky]

@bertsky could you resolve those conversations which are "done"? I know that it's still missing a section to describe the standalone REST processors, but I'll add it later, since I don't want to make this PR bigger (it's already big... ).

Done. Three points remain open for me, hopefully we can still work these through.

[tdoan2010]

Done. Three points remain open for me, hopefully we can still work these through.

Sorry, but I only found 2 (the arrow direction and the sync between producers & consumers). What do I miss? 😅

[bertsky]

What do I miss?

the one about an optional POST /workspace for METS URLs – since it's not in the swagger defs yet, and no mention of it being OPTIONAL in the markdown page, I assumed it's still open

[tdoan2010]

the one about an optional POST /workspace for METS URLs – since it's not in the swagger defs yet, and no mention of it being OPTIONAL in the markdown page, I assumed it's still open

I will update the openapi.yml file after this PR is merged. Then, that endpoint will be there and marked as OPTIONAL, as we discussed.

[bertsky]

Regarding https://github.com/OCR-D/spec/pull/222/files/ad6fe9eb018a40b823161331876f4afaad1827b3..3b2dee9d7c043f61ce04d3369b941f20ec78af2f – I do think sub-grouping is possible. It's been done in core in various places (e.g. ocrd-tool sub-group), too.

[tdoan2010]

Regarding https://github.com/OCR-D/spec/pull/222/files/ad6fe9eb018a40b823161331876f4afaad1827b3..3b2dee9d7c043f61ce04d3369b941f20ec78af2f – I do think sub-grouping is possible. It's been done in core in various places (e.g. ocrd-tool sub-group), too.

@kba said that it's really complicated to implement sub-command in the OCR-D Click Wrapper. So, better use option.

[bertsky]

@kba said that it's really complicated to implement sub-command in the OCR-D Click Wrapper. So, better use option.

I don't see it. It's just commands inside of groups inside of commands. A good example is ocrd-tool group. Implementation is easy. I could understand if the argument is that it's more complicated to document (esp. in the CLI). But then again, multiple related, interdependent options are also not easy not explain...

[kba]

I don't see it. It's just commands inside of groups inside of commands. A good example is ocrd-tool group. Implementation is easy. I could understand if the argument is that it's more complicated to document (esp. in the CLI). But then again, multiple related, interdependent options are also not easy not explain...

The problem is that we generate the click interface programmatically, so that processor developers only need

@click.command()                                                   
@ocrd_cli_options                                                  
def cli(*args, **kwargs):                                          
    return ocrd_cli_wrap_processor(MyProcessor, *args, **kwargs)

Now, we either require processors to change that to

@click.group()
@ocrd_cli_options
def cli(...):
   return ocrd_cli_wrap_processor(...)

@cli.command('server')
def worker_cli(...):
  return ocrd_cli_worker_subcommand_wrap(MyProcessor)

or find a way to wrap this as a single annotation. It's possible but tricky.

Whereas, for the ocrd command, it's trivial to create subcommands because they use the standard click-way of creating CLI.