Adam Retter

adam@evolvedbinary.com
 

Declarative Amsterdam
@ CWI, Amsterdam
2025-11-06

@adamretter

• Director of Evolved Binary

  • UK - Software, Consultancy, Training, and R&D

• Co-founder and Co-owner of eXist Solutions

  • Germany - TEI Publisher software

• Software Engineer / Prolific Open Source contributor

  • Elemental - Founder

  • eXist-db - 20 Years as Core contributor (last 9 as Main dev.)

  • RocksDB - 7 Years as RocksJava main developer

• W3C XQuery Working Group - Invited expert

• Founder of EXQuery, and creator of RESTXQ

• Enjoys Research and Development, and Snowboarding

• Web API

  • REST - Representational State Transfer

  • HATEOAS over HTTP

• XML Database

  • Elemental

1. PUT an XML "instance" to the store

2. GET an XML instance from the store

3. "do a HEAD on it"

4. POST an element, that is appended to the end of an XML instance

1. PUT an XML "instance" to the store

2. GET an XML instance from the store

3. "do a HEAD on it"

• HTTP HEAD Method

  • Retrieves only the HTTP Headers of a Resource. No content!

• Often includes:

  • Content-Length

  • Last-Modified

  • ETag

• Do we really need a dedicated HEAD method?

  • Might depend on the Client applications

  • Could just use conditional requests: e.g. If-Modified-Since

4. POST an element, that is appended to the end of an XML instance

• Steven's application is written in XForms

• XForms

  • Read/Update/Create Instances

  • An Instance is an XML Document

  • Most XForms implementations can HTTP GET/PUT/POST XML Documents

• XForms can prepare an updated XML document client-side

• XForms could just PUT the updated document over the top of an existing document

• Approaches

  • Explicit Update

    1. Create: PUT /my-collection

    2. Retrieve: GET /my-collection/my-document.xml

    3. Update: POST /my-collection/my-document.xml

  • Just Create/Replace and Retrieve

    1. Create: PUT /my-collection

    2. Retrieve: GET /my-collection/my-document.xml

    3. Replace: PUT /my-collection/my-document.xml

• REST Semantics for Update are unclear

• Should you use POST or PATCH?

1. Create a Document

   • HTTP PUT an XML document to the store

2. Retrieve a Document

   • HTTP GET an XML document from the store

   • Conditionally if modified

3. Update a Document

   • HTTP PATCH an XML document with modifications to the XML

4. List available Documents

   • HTTP GET a list of XML documents available from the store

5. Replace a Document

   • HTTP PUT an XML document to an existing URI

6. Delete a Document

   • HTTP DELETE an XML document from the store

7. JSON Support

   • Provide JSON versions of the API

• Standard - Open API (3.2)

• Swagger is a useful IDE for this

• Our API specification: DASP XForms API - dasp-xforms-api/1.0.0

1. Elemental's REST API

• No Code

• Served by Elemental's Web Server

1. Create a Document

   • HTTP PUT /exist/rest/db/dasp-documents/my-document.xml

     • Request body is the content for the XML document

     • Need to know document ID in advance!

2. Retrieve a Document

   • HTTP GET /exist/rest/db/dasp-documents/my-document.xml

     • Conditional: Supports If-Modified-Since request header

3. Update a Document

   • HTTP POST /exist/rest/db/dasp-documents/my-document.xml

     • Request body is an XUpdate document

4. List available Documents

   • HTTP GET /exist/rest/db/dasp-documents

5. Replace a Document

   • HTTP PUT /exist/rest/db/dasp-documents/my-document.xml

     • Request body is the new content for the XML document

6. Delete a Document

   • HTTP DELETE /exist/rest/db/dasp-documents/my-document.xml

7. JSON Support

   • Not without additional bespoke XQuery code!

• ✅ Delivered all 3 mandatory requirements

• 👍 Delivered 3 of 4 bouns requirements

• But:

  • API is very generic

• Just Elemental can be enough - No Code

• Java implementation was easy, should be same for others (e.g. Python, PHP, etc)

• RESTXQ implementation was simplest, least code

• In future: Auto-generate RESTXQ code from Open API

  • OpenAPI Tools issue #22273