In answer to the second part of the question about what the API would look like.

Being a restful API, it must adhere to the "standards".

1. Resources (URIs) No "verbs". The URL's describe resources, not functions (that is for the HTTP methods to describe)

2. HTTP methods - DEL to delete, POST to create, PUT to update, and GET to get

3. HTTP headers - Information about the type of data in the http "body"; JSON, attached files, XML, binary data, etc.

4. Query parameters - Modifications to the resource for optional search or , get "varieties".

5. Status Codes - Use the HTTP codes for return status, 200 OK, 201 Created, 404 Not found, 409 argument errors, 500 Internal server error, etc.

REST requires that you design your API as resources. In old XPP Web Services terms, rather than having listDoc(), getJT(), putJT(), and deleteDoc() functions, you think in terms of resources, and change the HTTP verb for the get/put type function.

So with a RESTful API everything XPP does has to revolve around a resource. What is a resource in XPP? For documents it is the XPP path (handle, class, group, job, and div). For Style its either a document path or a style library and the style type and base name.

For images, its the library and image name.

So rethinking XPP in REST terms, given an ID for job, division, or document processing, think of the path as an ID with a 5-part path: handle:class:group:job:div.

a POST to .../xpp/docs with the body being a JSON object of { path: "first:sdl:" } would make a first/CLS_sdl path. This would return a "201"

a DEL to  .../xpp/docs/first:sdl would delete the path. This would return a 200.

a GET to .../xpp/docs/first:sdl would return a JSON list of the groups within the "first" handle and  "sdl" class.

A GET to .../xpp/docs/first:xyvision:comp:blkmerge:/job/ticket would get the job ticket information as a JSON object where the members are the S/D field names.

Similarly a "POST" to .../xpp/docs/first:xyvision:comp:blkmerge:/job/ticket with the body containing the JSON object would change the values in the Job Ticket.

a GET to .../xpp/docs/first:xyvision:comp:blkmerge:1-blkmerge/processes/compose?options=-sx would get the output from the 'compose' process.

(Notice how this is turned around, so the URL's  are not thought of as "verbs". You are 'getting' the result of a resource, which consists of the "path" and the process you want to run on it.

a Get to .../xpp/docs/first:xyvision/status would return a JSON object with the OS path, whether the path exists, last modified date, etc.

Hopefully this gives you a feel for what is possible.

I believe the goal is to provide this low-level functional access to XPP. Applications can then be built on top of XPP for end-user functionality. Since we know our command line API, the "micro" web services hide the minute details you would be required to know handling the individual commands; ie. knowing that showpages can return non-zero success codes, or the arguments to commands so that the output does not include banner/status information that may get in the way of parsing the output.

The calls can be either. Most of the client functionality (like jquery), can make http get/post calls with callbacks when the data is ready. So it is completely up to the user on how they want to proceed. Of course XPP functionality-wise, you have to create a division, run toxsf, compose, and print in that order to get a PDF from XPP, but that is for the client to handle. For example, with callbacks if you are uploading images, there is no reason to upload one at a time. You can do multiples at the same time and just wait for them to all be completed with a callback.

Bottom line is that if you are calling a URL, it will eventually return something. When and where it is handled is up to the client.

Will the REST call be executed in a synchronous (high risk for timeouts) or in a asynchronous way?

Any hint on how the communication will look like?

Since this was discussed at XYUG 2017, I have had additional thoughts. Placed here for a discussion starter