Unit Tests for DTS API Responses

[philippepons]

1. Goals:

2. Send HTTP requests and verify the response status (expecting 200).

3. Retrieve the HTTP response in JSON-XML (with attributes format) and validate it against Relax-NG schemas. These schemas should be prepared based as much as possible on the DTS API documentation (version 1-alpha). Ideally, the schemas would be a Relax NG translation of the DTS specification!

Endpoint collection

• /api/dts/collection → expect 200
• /api/dts/collection?id=$resourceId
  • expect 200 if the resource is a collection
  • expect 200 if the resource is a document
• /api/dts/collection?id=$resourceId&nav=parents
  • expect 200 if the resource is a collection
  • expect 200 if the resource is a document

Additionally, validate the JSON-XML response with a Relax-NG schema based on the DTS documentation (v1-alpha).

Note: Is a single schema sufficient to cover the different parameter combinations for this endpoint?

Endpoint navigation

• /api/dts/navigation?resource=$resourceId → expect 200

• /api/dts/navigation?resource=$resourceId&down=2 → expect 200 (to confirm)

• /api/dts/navigation?resource=$resourceId&ref=$ref → expect 200

• /api/dts/navigation?resource=$resourceId&ref=$ref&down=2 → expect 200 (to confirm)

• /api/dts/navigation?resource=$resourceId&start=$start&end=$end → expect 200

• /api/dts/navigation?resource=$resourceId&start=$start&end=$end&down=2 → expect 200 (to confirm)

Additionally, validate the JSON-XML response with a Relax-NG schema based on the DTS documentation (v1-alpha).

Note: Is one single schema enough to support all parameter combinations here?

Endpoint document

• /api/dts/document?resource=$resourceId → expect 200

• /api/dts/document?resource=$resourceId&mediaType=html → expect 200

• /api/dts/document?resource=$resourceId&ref=$ref → expect 200

• /api/dts/document?resource=$resourceId&ref=$ref&mediaType=html → expect 200

• /api/dts/document?resource=$resourceId&start=$start&end=$end → expect 200

• /api/dts/document?resource=$resourceId&start=$start&end=$end&mediaType=html → expect 200

For this endpoint, no Relax-NG validation is required:

• Schemas for the registries are already available and used in other unit tests.
• As for the TEI file, its validation is the editors’ responsibility and falls outside the scope of these unit tests.

NB. : It may also be worth adding tests where 400 responses are expected (e.g., /api/dts/navigation without parameters).

[PonteIneptique]

@philippepons Just a reminder that @mromanello has developed https://github.com/mromanello/DTS-validator to check for compliancy. We are using it in a few repo, including https://github.com/distributed-text-services/MyDapytains/blob/main/.github/workflows/dts-validator.yml

[philippepons]

Thank you for the reminder and the links.
I actually tested DTS-Validator last Friday!

[mromanello]

Hello both @PonteIneptique @philippepons 👋
In fact, I've already included the validation of the DoTS demo endpoint in GH action that is run at every commit to the dts-validator (you can find the latest rest results here https://github.com/mromanello/DTS-validator/actions/runs/17128775548/artifacts/3819287051, in the file 3.10_report.html). Currently, the DoTS API has a very small issue in the entry endpoint which "blocks" further validation (the document endpoint is named documents plural instead of document singular as per the DTS specs).

@philippepons If you need help with decrypting the validator's error messages, do not hesitate to get in touch, I'll be happy to help! (I'm very aware that they can be very cryptic at times).