HTTP API¶
The web plugin also exposes all of its functions through a REST-ish API. You can use it to write small scripts or even for a full-blown Android or iPhone application, if you feel so inclined.
-
GET
/api/remote/templates
¶ Get option templates for all available plugins from a remote server.
Behaves exactly like
GET /api/templates
.Query Parameters: - server – Hostname of remote server
Response Headers: - Content-Type – application/json
-
GET
/api/remote/discover
¶ Get list of available postprocessing servers on network.
Response Headers: - Content-Type – application/json
Request JSON Object: - servers (array) – List of available server addresses
-
POST
/api/system/shutdown
¶ Shut down device.
Requires that the user running the application has permission to run shutdown -h now via sudo. Note that this endpoint will never send a response, clients should take this into account and set a low timeout value.
-
GET
/api/remote/plugins
¶ Get available plugin names from a remote server, grouped by type.
Behaves exactly like
GET /api/plugins
.Query Parameters: - server – Hostname of remote server
Response Headers: - Content-Type – application/json
-
GET
/api/remote/config
¶ Get default configuration from a remote server.
Behaves exactly like
GET /api/config
.Query Parameters: - server – Hostname of remote server
Response Headers: - Content-Type – application/json
-
POST
/api/system/reboot
¶ Reboot device.
Requires that the user running the application has permission to run shutdown -r now via sudo. Note that this endpoint will never send a response, clients should take this into account and set a low timeout value.
-
GET
/api/templates
¶ For every activated plugin, get all option templates.
Response Headers: - Content-Type – application/json
-
POST
/api/workflow
¶ Create a new workflow.
Request Headers: - Accept – application/json
Request JSON Object: - config (object) – Configuration for new workflow
- metadata (object) – Metadata for new workflow
Response Headers: - Content-Type – application/json
Status Codes: - 200 OK – When everything was OK.
- 400 Bad Request – When validation of configuration or metadata failed.
-
GET
/api/workflow
¶ Return a list of all workflows.
Response Headers: - Content-Type – application/json
-
GET
/api/plugins
¶ Get names of available and activated postprocessing and output plugins.
Response Headers: - Content-Type – application/json
Response JSON Object: - postprocessing (array) – List of postprocessing plugin names
- output (array) – List of output plugin names
-
GET
/api/config
¶ Get global default configuration.
Response Headers: - Content-Type – application/json
-
PUT
/api/config
¶ Update global default configuration.
If core or web settings were modified, the application will be restarted.
Request Headers: - Content-Type – application/json
Response Headers: - Content-Type – application/json
-
POST
/api/reset
¶ Restart the application.
Note that this endpoint will never send a response, clients should take this into account and set a low timeout value.
-
GET
/api/isbn
¶ Search for ISBN records.
Query Parameters: - q – Search query
Response Headers: - Content-Type – application/json
Response JSON Object: - results (array) – Matching ISBN records
Status Codes: - 200 OK – When the query was successful
- 400 Bad Request – When no search query was supplied
-
GET
/api/log
¶ Get application log.
Query Parameters: - start – Index of first message (default: 0)
- count – Number of messages to return (default: 50)
- level – Maximum log level to be included in messages (default: INFO)
Response Headers: - Content-Type – application/json
Response JSON Object: - total_num (boolean) – Total number of messages
- messages (array) – Requested messages
-
GET
/api/workflow/
(workflow: workflow)/page/
(int: number)/
(img_type)/thumb
¶
-
GET
/api/workflow/
(workflow: workflow)/page/
(int: number)/
(img_type)/
(plugname)/thumb
¶ Get thumbnail for a page image.
-
POST
/api/workflow/
(workflow: workflow)/page/
(int: number)/
(img_type)/crop
¶ Crop a page image in place.
-
GET
/api/workflow/
(workflow: workflow)/page/
(int: number)/
(img_type)¶
-
GET
/api/workflow/
(workflow: workflow)/page/
(int: number)/
(img_type)/
(plugname)¶ Get image for requested page.
Parameters: - workflow (str) – UUID or slug for a workflow
- number (int) – Capture number of requested page
- img_type (str, one of raw or processed) – Type of image
- plugname (str) – Only applicable if img_type is processed,
selects the desired processed file by its key in the
spreads.workflow.Workflow.processed_images
dictionary.
Query Parameters: - width – Optionally scale down image to the desired width
- format – Optionally convert image to desired format. If browser is specified, non-JPG or PNG images will be converted to PNG.
Response Headers: - Content-Type – Depends on value of format, by default the mime-type of the original image.
-
GET
/api/workflow/
(workflow: workflow)/output/
(fname)¶ Download an output file.
Parameters: - workflow (str) – UUID or slug for the workflow to download from
- fname (str) – Filename of the output file to download
Status Codes: - 200 OK – Everything OK.
- 404 Not Found – Workflow or filename not found
-
GET
/api/workflow/
(workflow: workflow)/page/
(int: number)¶ Get a single page.
Parameters: - workflow (str) – UUID or slug for a workflow
- number (int) – Capture number of requested page
Response Headers: - Content-Type – application/json
-
DELETE
/api/workflow/
(workflow: workflow)/page/
(int: number)¶ Remove a single page from a workflow.
-
POST
/api/workflow/
(workflow: workflow)/prepare_capture
¶ Prepare capture for the requested workflow.
-
POST
/api/workflow/
(workflow: workflow)/finish_capture
¶ Wrap up capture process on the requested workflow.
-
GET
/api/workflow/
(workflow: workflow)/download
¶ - Redirect to download endpoint (see
spreadsplug.web.handlers.ZipDownloadHandler
orspreadsplug.web.handlers.TarDownloadHandler
) with proper filename set.
Parameters: - workflow (str) – UUID or slug for the workflow to download
Query Parameters: - fmt – Archive format for download (zip or tar, default: tar)
Status Codes: - 302 Found – Redirects to
GET /api/workflow/(str:workflow_id)/download/(str:workflow_slug).(str:archive_extension)
-
POST
/api/workflow/
(workflow: workflow)/transfer
¶ Enqueue workflow for transfer to an attached USB storage device.
Requires that the python-dbus package is installed.
Once the transfer was succesfully enqueued, watch for the
spreadsplug.web.tasks.on_transfer_started
which is emitted when the transfer actually started and subsequentlyspreadsplug.web.tasks.on_transfer_progressed
andspreadsplug.web.tasks.on_transfer_completed
.Parameters: - workflow (str) – UUID or slug for the workflow to be transferred
Status Codes: - 200 OK – When the transfer was successfully enqueued.
- 500 Internal Server Error – When the python-dbus package was not found.
- 503 Service Unavailable – When no removable USB device could be found for mounting.
-
POST
/api/workflow/
(workflow: workflow)/capture
¶ Trigger a capture on the requested workflow.
Optional parameter ‘retake’ specifies if the last shot is to be retaken.
Returns the number of pages shot and a list of the pages captured by this call in JSON notation.
-
POST
/api/workflow/
(workflow: workflow)/process
¶ Enqueue the specified workflow for postprocessing.
-
POST
/api/workflow/
(workflow: workflow)/submit
¶ Enqueue workflow for submission to a postprocessing server.
It is possible to submit a configuration object that should be used on the remote end for the workflow. Optionally, it can be specified if postprocessing and output generation should immediately be enqueued on the remote server.
Once the submission was succesfully enqueued, watch for the
spreadsplug.web.tasks.on_submit_started
which is emitted when the submission actually started and subsequentlyspreadsplug.web.tasks.on_submit_progressed
,spreadsplug.web.tasks.on_submit_completed
andspreadsplug.web.tasks.on_submit_error
.Request Headers: - Accept – application/json
Parameters: - workflow (str) – UUID or slug for the workflow to be submitted
Request JSON Object: - server (string) – Address of server to submit to
- config (object) – Configuration to use for workflow on remote server.
- start_process (boolean) – Whether to enqueue workflow for post-processing on the remote server.
- start_output (boolean) – Whether to enqueue workflow for output generation on the remote server.
Status Codes: - 200 OK – When the transfer was successfully enqueued.
- 400 Bad Request – When no postprocessing server was specified
- 500 Internal Server Error – When the python-dbus package was not found.
- 503 Service Unavailable – When no removable USB device could be found for mounting.
-
POST
/api/workflow/
(workflow: workflow)/output
¶ Enqueue the specified workflow for output generation.
-
GET
/api/workflow/
(workflow: workflow)/page
¶ Get all pages for a workflow.
Parameters: - workflow (str) – UUID or slug for a workflow
Response Headers: - Content-Type – application/json
-
DELETE
/api/workflow/
(workflow: workflow)/page
¶ Delete multiple pages from a workflow with one request.
-
GET
/api/workflow/
(workflow: workflow)¶ Return a single workflow.
Parameters: - workflow (str) – UUID or slug for a workflow
Response Headers: - Content-Type – application/json
-
PUT
/api/workflow/
(workflow: workflow)¶ Update a single workflow.
Parameters: - workflow (str) – UUID or slug for the workflow to be updated
Request JSON Object: - config (object) – Updated workflow configuration
- metadata (object) – Updated workflow metadata
Response Headers: - Content-Type – application/json
Status Codes: - 200 OK – When everything was OK.
- 400 Bad Request – When validation of configuration or metadata failed.
-
DELETE
/api/workflow/
(workflow: workflow)¶ Delete a single workflow from database and disk.
Parameters: - workflow (str) – UUID or slug for the workflow to be updated
Status Codes: - 200 OK – When deletion was succesful
-
GET
/api/isbn/
(isbn)¶ Get metadata for a given ISBN number.
Parameters: - isbn (str/unicode with valid ISBN-10 or ISBN-13, optionally prefixed with isbn:) – ISBN number to retrieve metadata for
Response Headers: - Content-Type – application/json
Status Codes: - 200 OK – When the ISBN was valid and a match was found.
- 400 Bad Request – When the ISBN was invalid or no match was found.
-
GET
/static/
(path: filename)¶ Function used internally to send static files from the static folder to the browser.
New in version 0.5.