[TYPO3-doc] RFC: Request rendering through web service

[Karsten Dambekalns]

I am working on TYPO3.Docs right now, and the next step would be the possibility to request rendering of documentation via a web service.

So, we deal with packages and documents, packages are where documentation (source) might be in, and documents are the result of rendering those. Since REST deals with resources, we obviously need to communicate any change to a package, if we want a new render job to be done.

My suggestion:

* a POST will be done to docs.typo3.org/api/packages
* with a JSON payload describing the package.

That payload contains the information needed to identify a package. At first sight that would be the package key, but that is not as easy. The code right now has a "strange" understanding of what the package key is, and we have multiple candidates for what it could be: extension key, Flow package key, composer name.

Add to that the fact that any package could be from TER or git (or composer, eventually), and rendering requests for new packages should work as well, introduces some more needed data.

My suggestion for the payload:

repositoryType: ter|git
packageKey: ... (for ter)
repository: ... (for git)

The latter would be the full URI to fetch from (i.e. what you would give to "git clone" as well).

The request would be answered with an appropriate status code (of course) and a JSON body that includes any (error) messages and some id that can be used to check the status of the job (via jobs/<id> or similar) that was hopefully queued.

Whatchathink?

Regards,
Karsten
-- 
Karsten Dambekalns
TYPO3 Developer, Neos / Flow Team

TYPO3 .... inspiring people to share!
Get involved: typo3.org