Routes
Ferroseek serves a subset of the Elasticsearch 7.17 REST API. Requests and responses have the same shape as Elasticsearch’s. Every response, including errors, carries Content-Type: application/json; charset=UTF-8 and X-Elastic-Product: Elasticsearch; the official clients (7.14 and later) refuse a server without that header.
With a static index, one Worker serves one index, named by the index builder’s --name; in the examples it is products. With the indexing API, a Worker serves every index in its R2 bucket (up to the memory budget) and also accepts the write routes.
Route table
Section titled “Route table”| Method | Path | Answer |
|---|---|---|
GET, HEAD |
/ |
Cluster information, with version.number "7.17.4" |
GET, POST |
/{index}/_search |
Search; body as in Queries |
GET, POST |
/{index}/_count |
{"count": n, "_shards": …}; optional body {"query": …} |
GET, HEAD |
/{index}/_doc/{id} |
The document, or 404 with "found": false |
GET, POST |
/{index}/_mget |
{"docs": […]}; body {"ids": […]} or {"docs": [{"_id": …}]} |
GET, HEAD |
/{index} |
Aliases, mappings and settings of the index (indices of the indexing API only) |
GET |
/{index}/_mapping |
The mapping, properties sorted by name |
GET, POST |
/_msearch, /{index}/_msearch |
Several searches in one request |
A request for an index that does not exist answers 404 index_not_found_exception, as Elasticsearch does.
{ "name": "ferroseek", "cluster_name": "ferroseek", "cluster_uuid": "ferroseek", "version": { "number": "7.17.4", "build_flavor": "default", "build_type": "ferroseek", "lucene_version": "8.11.1", "minimum_wire_compatibility_version": "6.8.0", "minimum_index_compatibility_version": "6.0.0-beta1" }, "tagline": "You Know, for Search"}(Some version fields are left out here.) Clients use this route to check what they are talking to; Ferroseek reports the Elasticsearch version whose behaviour it reproduces.
_search
Section titled “_search”GET and POST behave the same. With no body, the search matches all documents and returns the first 10. The body accepts query, post_filter, aggs (or aggregations), sort, from, size, _source, track_total_hits, track_scores and search_after. Anything else is rejected; see Limits and differences.
_count
Section titled “_count”The body is optional and may only contain query:
curl -s http://localhost:4090/products/_count \ -H 'Content-Type: application/json' \ -d '{ "query": { "term": { "color": "red" } } }'{ "count": 8484, "_shards": { "total": 1, "successful": 1, "skipped": 0, "failed": 0 } }_doc/{id}
Section titled “_doc/{id}”{ "_index": "products", "_type": "_doc", "_id": "SKU-000001", "_version": 1, "_seq_no": 0, "_primary_term": 1, "found": true, "_source": { "sku": "SKU-000001", "name": "Sonece Wireless Crib A100", "…": "…" }}An unknown id answers 404 with {"_index": "products", "_type": "_doc", "_id": "…", "found": false}.
_msearch
Section titled “_msearch”The body is NDJSON: a header line, then a body line, for each search. A header may only contain index, and may be empty ({}). A search whose header names no index runs on the index in the path (/{index}/_msearch); on /_msearch, on the one index that the other headers of the request name, or on the only index the Worker serves. If none of these gives exactly one index, that search answers 400 illegal_argument_exception “[ferroseek] _msearch item without an index”; Elasticsearch would search every index. The response has one entry per search, each either a search response with "status": 200 or an error object.
printf '%s\n' \ '{"index":"products"}' '{"size":0,"query":{"term":{"color":"red"}}}' \ '{"index":"products"}' '{"size":0}' \| curl -s http://localhost:4090/_msearch \ -H 'Content-Type: application/x-ndjson' --data-binary @-At most 32 searches per request, and they share one CPU budget and one response-size budget. See Limits and differences.
Query-string parameters
Section titled “Query-string parameters”On the search routes only pretty is accepted (?pretty or ?pretty=true), which indents the response. Any other parameter, including ones Elasticsearch accepts such as ?size= or ?q=, is rejected:
{ "error": { "type": "illegal_argument_exception", "reason": "request [/products/_search] contains unrecognized parameter: [size]", "root_cause": [ { "type": "illegal_argument_exception", "reason": "request [/products/_search] contains unrecognized parameter: [size]" } ] }, "status": 400}Put search options in the request body instead.
Unknown routes and methods
Section titled “Unknown routes and methods”- A known route with the wrong method, such as
DELETE /products/_search, answers405withillegal_argument_exception(“Incorrect HTTP method for uri …”). - Any other path answers
400withillegal_argument_exception(“no handler found for uri … and method …”).
Without the indexing API (a static index), the write routes below answer 400 illegal_argument_exception with the reason [ferroseek] unsupported: writes are not enabled (no writer binding).
Write routes
Section titled “Write routes”Available when the Worker has the writer binding (see Deploy with the indexing API). They are executed by the index’s writer Durable Object; the Worker checks credentials and body size and forwards the request. Responses have Elasticsearch 7.17’s shapes, key order included; see Write through the API for examples.
| Method | Path | Answer |
|---|---|---|
PUT |
/{index} |
{"acknowledged":true,"shards_acknowledged":true,"index":…}; body settings, mappings, aliases (empty) |
DELETE |
/{index} |
{"acknowledged":true} |
GET, PUT |
/{index}/_settings |
Read or change refresh_interval and number_of_replicas |
PUT, POST |
/{index}/_doc/{id} |
201 created or 200 updated |
POST |
/{index}/_doc |
201 with a generated 20-character _id |
PUT, POST |
/{index}/_create/{id} |
201, or 409 version_conflict_engine_exception if it exists |
DELETE |
/{index}/_doc/{id} |
200 deleted, or 404 with "result":"not_found" (and the full write body) |
POST |
/{index}/_update/{id} |
doc, doc_as_upsert, upsert, detect_noop, _source; 200 updated or noop, 201 created by an upsert |
POST, PUT |
/_bulk, /{index}/_bulk |
Per-item results in request order |
POST, GET |
/{index}/_refresh |
{"_shards":{"total":…,"successful":1,"failed":0}} |
GET /{index}/_doc/{id}, HEAD of it and _mget are real-time by default: they are answered by the writer and see unrefreshed writes. With ?realtime=false, or when the deployment sets realtimeGet: "reader", they read the searchable generation.
Parameters accepted on write routes, with Elasticsearch’s values and errors: refresh (true, empty, false, wait_for), op_type (index, create), if_seq_no with if_primary_term, version with version_type (external, external_gte), retry_on_conflict (accepted and ignored: one writer per index cannot conflict with itself), _source (_update only), timeout and wait_for_active_shards (validated, ignored), pretty. Any other parameter answers the contains unrecognized parameter error above.
Not supported, 400 illegal_argument_exception with [ferroseek] unsupported: …: scripts (in _update and in bulk update items), _update_by_query, _delete_by_query, _reindex, mapping changes (PUT /{index}/_mapping), aliases, and index-less or multi-index forms of writes and index management (/_refresh, DELETE /a,b, DELETE /logs-*, _all).
Credentials
Section titled “Credentials”FERROSEEK_USERNAME, FERROSEEK_PASSWORD and FERROSEEK_API_KEY grant reads only. FERROSEEK_WRITE_USERNAME, FERROSEEK_WRITE_PASSWORD and FERROSEEK_WRITE_API_KEY grant reads and writes. A read-only credential on a write route answers 403, in the shape Elasticsearch uses for a user without the privilege:
{"error":{"root_cause":[{"type":"security_exception","reason":"action [indices:data/write/index] is unauthorized for user [reader] with roles [ferroseek_read_only], this action is granted by the index privileges [create_doc,create,index,write,all]"}],"type":"security_exception","reason":"action [indices:data/write/index] is unauthorized for user [reader] with roles [ferroseek_read_only], this action is granted by the index privileges [create_doc,create,index,write,all]"},"status":403}Missing or wrong credentials answer 401, as on the search routes. When read-only credentials are configured and write credentials are not, every write is refused.
Internal routes
Section titled “Internal routes”Ferroseek’s own operations, also forwarded to the writer, and only with write credentials:
| Method | Path | Answer |
|---|---|---|
POST |
/_ferroseek/adopt |
Adopts an offline-built image already uploaded to the bucket; body {"index","settings","mappings","base_key"}; see Adopt an offline build |
POST |
/_ferroseek/compact?index= |
Compacts the index now and answers with the outcome and the new manifest |
GET |
/_ferroseek/status?index= |
The writer’s state: the published manifest, pending counts, objects, compactions, recent publish timings |