Some queries we can fit into a URL, for example a /:directory query lists the sub-documents of a certain path.

For complicated and interesting queries, it is unrealistic to encode a complicated query into the URL.

Outside the scope of this document: the actual schema of our queries. This is an ongoing area of research that @Untitled Contact is looking at.

Post API

This can be managed by introducing a new POST HTTP endpoint at (for example) <HMSiteDomain>/hm/api/query where you will have a query encoded as JSON or CBOR, and the server will return with the response.

This works, but comes with 2 downsides:

This approach will not be cached by CDNs who are expecting GET requests

Overhead: the query must be uploaded every time it is fetched

This can be solved with PeristedQueries

Persisted Queries

For each POST to /hm/api/query, the backend will respond with a QueryCID header. The query is persisted to IPFS

Now the client may re-fetch the same query with GET /hm/api/query/<QueryCID>

Now these sophisticated queries can be easily cached at the HTTP cache layer, and they are very light to send.

This general approach of query persistence is commonly used in the industry, and can be an improvement to security (for example you can disallow anonymous queries that are not persisted)