Planned API extensions

The first two extensions are designed with the #63 Printing Previews feature in mind. The previews will be generated on the server (likely in a Celery worker), not on the client device. This requires uploading documents before the request to start the print job is made. As the user might want to modify the print settings after generating a preview, new endpoints and operations for modifying a print job are needed. Without them, the client would have to create new jobs for each preview, which would require reuploading the documents each time.

Job modifications

The goal of this extension is to allow the client to perform the following actions on a job:

1. Modify job attributes
2. Get the document (file) list
3. Delete an uploaded document
4. Change the document print order

The first two actions can be implemented using standard IPP operations.

Modify job attributes

RFC 3380 defines the Set-Job-Attributes IPP operation, which does exactly what we need for this action.

The REST API endpoint for this action could be PATCH /api/jobs/:id/. Alternatively a POST action could be added. While a PATCH request is not required to be idempotent, our implementation of this endpoint probably should be. See the MDN docs for the PATCH request method.

The IPP operation must be atomic, which means it must either change all requested attributes or none. The REST API endpoint should also be atomic.

The IPP operation is also sparse, meaning the client only has to provide the attributes which it wishes to change. This REST API endpoint should also allow sparse updates so that the addition of a new attribute is not a breaking change.

Unsupported job configuration handling

The IPP operations Print-Job, Validate-Job, Create-Job and Set-Job-Attributes should verify if the selected print configuration is valid and reject the operation if it is not (e.g., if some pair of provided attribute values is conflicting).

The same behavior might not be the optimal solution for the REST API. When the user is modifying the print configuration, it is desirable to store it on the server after each change in the UI (with proper throttling/debouncing on the webapp side). This way refreshing the page will not cause data loss, as the web app can retrieve the stored configuration after the reload.

The suggested behavior in this case is to allow setting syntactically valid attributes that result in a configuration not supported by the selected printer in requests to POST /api/jobs/create_job/ and PATCH /api/jobs/:id/. If the selected job configuration is invalid, the responses to these requests should indicate operation success (a 2xx status code) but should include a errors field in the response body, indicating the errors in the selected configuration. A human-readable warning message should be included for displaying in the webapp UI. The output could also include the warnings in a structured form, just like it would be returned from the IPP operations.

The server should return a failure response for calls to POST /api/jobs/submit/ and POST /api/jobs/:id/run_job/ if the current job configuration is invalid. The same validation should also happen when executing IPP operations which start the print job (Print-Job, Send-Document with last-document set to true and Close-Job) and the Validate-Job operation, as the configuration might be invalid if it has been created via IPP but modified using the REST API.

The list of errors could also be retrievable using a new endpoint or could be included in the response to calls to the GET /api/job/:id/ endpoint.

Get the document list

The IPP operations suitable for this action are Get-Documents and Get-Document-Attributes.

In the REST API the file list could be returned either in the response from GET /api/job/:id/ or using a new ViewSet endpoint supporting the requests to GET /api/job/:id/documents/ and GET /api/job/:id/documents/:doc_id/. The ViewSet solution follows the convention of providing a 1 to 1 mapping of the REST API endpoints to IPP operations.

Delete document

A simple DELETE /api/job/:id/documents/:doc_id/ endpoint could accomplish this action in the REST API.

There is no IPP operation suitable to accomplish this action:

• The Delete-Document action defined in the PWG 5100.5-2003 Standard for IPP Document Object standard has since been obsoleted and must not be implemented. Even if it wasn't, it could not be used for this purpose, as it can only be used by the printer's operators and administrators, not end-users.
• The Cancel-Document operation has undesirable semantics. If the Resubmit-Job operation or another way to rerun jobs is implemented, the previously canceled documents should get printed again.

As such, this endpoint should not be marked as mapping to Delete-Document or Cancel-Document.

Modify document order

For this action a POST /api/job/:id/documents/reorder endpoint could be provided accepting the new document print order in the request body, for example:

{
  "order": ["B", "A", "C"]
}

The server should verify that all documents are included exactly once.

There does not exist a standard IPP operation for this action.

Printing previews in the REST API

This feature is described in PR #63.

The preview request generates (low-quality) images for each page in the PDF, and any additional metadata needed to display the preview. Techniques like CSS Sprites could be used to load all images in a single request.

As both the print and preview requests create the same PDF file, job-scoped caching could be used to avoid generating the same PDF multiple times if the settings and input files have not changed.

Please note that the preprocessing job might take a while to complete, and it is done asynchronously in a Celery worker. The API design should account for this:

• when a new preview is requested, the previous request generation celery task should probably be canceled.
• the behavior when a print is requested while the preview is being generated should be specified.
• there needs to be a way for the server to notify the client that the preview is ready. Long-running HTTP requests or server-side events could be used. Consider separating the endpoints for a preview request and preview image retrieval.

Printing previews via IPP

See PR #69.

Per-document print attribute overrides

This feature is described in PR #94.

This could be an opportunity to implement the PWG 5100.5-2024 – IPP Document Object v1.2 standard.

Issues with the IPP operations for document management actions

The Get-Documents, Get-Document-Attributes map directly to the GET /api/job/:id/documents/ and GET /api/job/:id/documents/:doc_id/ operations described in the Job modifications section above.

This IPP standard uses sequential document numbers for identifying the documents. The obsoleted Delete-Document operation creates a gap in the numbering. This numbering also represents the order in which the documents will be processed. This presents an issue for the modify document order action, as the document numbers used by IPP will need to be changed after modifying the document order.

One possible solution to this issue would be to assign new numbers to all the documents if the order gets changed. For example, assume there are three documents A, B, C initially in this order identified in IPP by the numbers: A:1, B:2, C:3. When the REST API client changes the order to C, B, A, these documents will be assigned the numbers C:4, D:5, E:6. Since in this scenario the number of a document can change, the REST API should use different, persistent document IDs.

The Cancel-Document operation required by this standard is semantically different from the proposed document delete endpoint. A canceled document should remain in the document list and will get printed if the job is resubmitted. The webapp should display this canceled status in the job file list.