Skip to content

Product Files Tests

The Product Files Tests resource provides an endpoint for reading, searching and writing the result(s) of a file test (e.g. the result of the tool epubcheck or pdftools for pre-flight-checks)

URL:

https://api.openpublishing.com/resource/v3/products/[ID]/files/[ID]/tests
https://api.openpublishing.com/resource/v3/products/[ID]/files/[ID]/tests/[ID]

Supported methods:

POST to products/[ID]/files/[ID]/tests for storing the test result of a test

The payload in the body contains the test result in the following JSON object:

  • result (string): the result of the test:
  • passed: the test passed successfully
  • failed: the test did not pass, it contains errors
  • type (string) [mandatory]: type/name of the test (e.g. epubcheck, pdftoolbox)
  • checked_at (numeric): UNIX timestamp when the test was executed
  • duration_in_ms (numeric): execution time in milliseconds
  • messages (array): list of all message objects returned by test, that have the following format:
  • check (string): type of the message:
    • info: general information
    • warning: warning message
    • error: error message (if set, the test is considered as failed)
  • text (string): text message

PUT to products/[ID]/files/[ID]/tests/[ID] to overwrite information of a specific test

DELETE to products/[ID]/files/[ID]/tests/[ID] to delete a specific test

GET to products/[ID]/files/[ID]/tests/[ID] for retrieving information about a specific test

GET to products/[ID]/files/[ID]/tests for retrieving information about all tests

GET to products/[ID]/files/[ID]/tests?[search parameters] for retrieving information about specific tests:

  • type (string): searches for all tests of the specific type (e.g. epubcheck)
  • result (string): searches for all tests with a specific result (e.g. failed)
  • errors (boolean): if true searches for all tests with errors otherwise for all tests without errors
  • warnings (boolean): if true searches for all tests with warnings otherwise for all tests without warnings

Example JSON

{
   "result": "passed",
   "type": "epubcheck",
   "checked_at": 1667337197,
   "duration_in_ms": 1859,
   "messages": []
}

{
   "result": "failed",
   "type": "epubcheck" ,
   "checked_at": 1667337197,
   "duration_in_ms": 1859,
   "messages": [
      {
         "check": "info",
         "text": "Validating using EPUB version 2.0.1 rules."
      },
      {
         "check": "error",
         "text": "The EPUB 9781234567897.epub contains errors and could not be validated: Validating using EPUB version 2.0.1 rules.\nERROR(CSS-010): /storage/document/1249/1249573/9781234567897.epub/OEBPS/Text/content-2xhtml(8,110):\nStylesheet of type other than \"text/css\" must have a fallback."
      }
   ]
}

{
   "result": "passed",
   "type": "antivirus",
   "checked_at": 1667337197,
   "duration_in_ms": 1859,
   "messages": [
      {
            "check": "warning",
            "text": "9781234567897.epub: contains executable JavaScript code."
      }
   ],
}

Example GET URLs

https://api.openpublishing.com/resource/v3/products/12345/files/678/tests
https://api.openpublishing.com/resource/v3/products/12345/files/6789/tests/9876
https://api.openpublishing.com/resource/v3/products/12345/files/678/tests?result=failed
https://api.openpublishing.com/resource/v3/products/12345/files/678/tests?warnings=true
https://api.openpublishing.com/resource/v3/products/12345/files/678/tests?type=epubcheck&result=failed