Idea Delivered

A RESTful Web Services API was added to the product with XPP 9.3.

It is available, and is distributed for use with any new installation or upgrade as of the XPP 9.3 release.

XPP Restful API Web Services

Replace Web Services with a RESTful API that is URL addressable for XPP functionality.

Low-level "micro" services (toxsf, compose, print, citi, etc) supported by XPP, that can be built upon for more high level customized  functionality.

Steve Piercey
Parents

  • 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.

Comment

  • 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.

Children
No Data