{ "openapi": "3.0.3", "info": { "title": "RustSearch optional OpenSearch API", "version": "0.1.0", "description": "Experimental, read-only subset of the OpenSearch wire API backed by the existing RustSearch bibliographic index. Disabled by default and loopback only. No Elasticsearch compatibility claim. Does not apply Koha user/OPAC visibility rules; trusted local integrations only. No original _source, writes, mappings, aggregations, sorting, scrolling, or cluster administration. from + size <= 10000. Native Koha routes and index schema are unchanged." }, "servers": [ { "url": "/opensearch/v1" } ], "paths": { "/{index}/_search": { "post": { "operationId": "postSearch", "summary": "Search native bibliographic records", "parameters": [ { "name": "index", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "biblios" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } }, "400": { "description": "Unsupported or invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown index or endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Engine error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequest" } } } } }, "get": { "operationId": "getSearch", "summary": "Search native bibliographic records", "parameters": [ { "name": "index", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "biblios" ] } }, { "name": "_source", "in": "query", "required": true, "schema": { "type": "boolean", "enum": [ false ], "description": "Required false. Original JSON source is not retained." } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 0 } }, { "name": "size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 100, "default": 10 } }, { "name": "track_total_hits", "in": "query", "required": false, "schema": { "type": "boolean", "enum": [ true ], "default": true } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } }, "400": { "description": "Unsupported or invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown index or endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Engine error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "GET supports URL parameters only; use POST for a query DSL body. Returns match_all when no query body is supplied." } }, "/{index}/_count": { "post": { "operationId": "postCount", "summary": "Count matching bibliographic records", "parameters": [ { "name": "index", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "biblios" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountResponse" } } } }, "400": { "description": "Unsupported or invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown index or endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Engine error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountRequest" } } } } }, "get": { "operationId": "getCount", "summary": "Count matching bibliographic records", "parameters": [ { "name": "index", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "biblios" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountResponse" } } } }, "400": { "description": "Unsupported or invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown index or endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Engine error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "GET without a body counts all records. Use POST to send a query." } }, "/": { "get": { "operationId": "getCapabilities", "summary": "Read API identity and supported features", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Capabilities" } } } }, "413": { "description": "Request body exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "Query": { "type": "object", "minProperties": 1, "maxProperties": 1, "description": "Exactly one supported query type. match uses native Unicode folding and OR by default; operator and is supported. term is literal, without analysis. bool accepts must/filter/must_not/should and integer minimum_should_match. Maximum depth 16 and 256 query nodes. Unsupported types/options fail with 400.", "additionalProperties": false, "properties": { "match_all": { "type": "object", "additionalProperties": false }, "match_none": { "type": "object", "additionalProperties": false }, "match": { "type": "object", "minProperties": 1, "maxProperties": 1, "additionalProperties": false, "properties": { "title": { "oneOf": [ { "type": "string", "maxLength": 4096 }, { "type": "object", "required": [ "query" ], "additionalProperties": false, "properties": { "query": { "type": "string", "maxLength": 4096 }, "operator": { "type": "string", "enum": [ "and", "or" ], "default": "or" } } } ] }, "author": { "oneOf": [ { "type": "string", "maxLength": 4096 }, { "type": "object", "required": [ "query" ], "additionalProperties": false, "properties": { "query": { "type": "string", "maxLength": 4096 }, "operator": { "type": "string", "enum": [ "and", "or" ], "default": "or" } } } ] }, "subject": { "oneOf": [ { "type": "string", "maxLength": 4096 }, { "type": "object", "required": [ "query" ], "additionalProperties": false, "properties": { "query": { "type": "string", "maxLength": 4096 }, "operator": { "type": "string", "enum": [ "and", "or" ], "default": "or" } } } ] }, "keyword_extra": { "oneOf": [ { "type": "string", "maxLength": 4096 }, { "type": "object", "required": [ "query" ], "additionalProperties": false, "properties": { "query": { "type": "string", "maxLength": 4096 }, "operator": { "type": "string", "enum": [ "and", "or" ], "default": "or" } } } ] } } }, "match_phrase": { "type": "object", "minProperties": 1, "maxProperties": 1, "additionalProperties": false, "properties": { "title": { "oneOf": [ { "type": "string", "maxLength": 4096 }, { "type": "object", "required": [ "query" ], "additionalProperties": false, "properties": { "query": { "type": "string", "maxLength": 4096 } } } ] }, "author": { "oneOf": [ { "type": "string", "maxLength": 4096 }, { "type": "object", "required": [ "query" ], "additionalProperties": false, "properties": { "query": { "type": "string", "maxLength": 4096 } } } ] }, "subject": { "oneOf": [ { "type": "string", "maxLength": 4096 }, { "type": "object", "required": [ "query" ], "additionalProperties": false, "properties": { "query": { "type": "string", "maxLength": 4096 } } } ] }, "keyword_extra": { "oneOf": [ { "type": "string", "maxLength": 4096 }, { "type": "object", "required": [ "query" ], "additionalProperties": false, "properties": { "query": { "type": "string", "maxLength": 4096 } } } ] } } }, "term": { "type": "object", "minProperties": 1, "maxProperties": 1, "additionalProperties": false, "properties": { "title": { "oneOf": [ { "type": "string", "maxLength": 4096, "minLength": 1 }, { "type": "object", "required": [ "value" ], "additionalProperties": false, "properties": { "value": { "type": "string", "maxLength": 4096, "minLength": 1 } } } ] }, "author": { "oneOf": [ { "type": "string", "maxLength": 4096, "minLength": 1 }, { "type": "object", "required": [ "value" ], "additionalProperties": false, "properties": { "value": { "type": "string", "maxLength": 4096, "minLength": 1 } } } ] }, "subject": { "oneOf": [ { "type": "string", "maxLength": 4096, "minLength": 1 }, { "type": "object", "required": [ "value" ], "additionalProperties": false, "properties": { "value": { "type": "string", "maxLength": 4096, "minLength": 1 } } } ] }, "keyword_extra": { "oneOf": [ { "type": "string", "maxLength": 4096, "minLength": 1 }, { "type": "object", "required": [ "value" ], "additionalProperties": false, "properties": { "value": { "type": "string", "maxLength": 4096, "minLength": 1 } } } ] }, "isbn": { "oneOf": [ { "type": "string", "maxLength": 4096, "minLength": 1 }, { "type": "object", "required": [ "value" ], "additionalProperties": false, "properties": { "value": { "type": "string", "maxLength": 4096, "minLength": 1 } } } ] }, "biblionumber": { "oneOf": [ { "oneOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[0-9]+$" } ] }, { "type": "object", "required": [ "value" ], "additionalProperties": false, "properties": { "value": { "oneOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[0-9]+$" } ] } } } ] } } }, "ids": { "type": "object", "additionalProperties": false, "required": [ "values" ], "properties": { "values": { "type": "array", "maxItems": 256, "items": { "oneOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[0-9]+$" } ] } } } }, "bool": { "type": "object", "additionalProperties": false, "properties": { "must": { "oneOf": [ { "$ref": "#/components/schemas/Query" }, { "type": "array", "items": { "$ref": "#/components/schemas/Query" }, "maxItems": 256 } ] }, "filter": { "oneOf": [ { "$ref": "#/components/schemas/Query" }, { "type": "array", "items": { "$ref": "#/components/schemas/Query" }, "maxItems": 256 } ] }, "must_not": { "oneOf": [ { "$ref": "#/components/schemas/Query" }, { "type": "array", "items": { "$ref": "#/components/schemas/Query" }, "maxItems": 256 } ] }, "should": { "oneOf": [ { "$ref": "#/components/schemas/Query" }, { "type": "array", "items": { "$ref": "#/components/schemas/Query" }, "maxItems": 256 } ] }, "minimum_should_match": { "type": "integer", "minimum": 0, "description": "Cannot exceed the number of should clauses; percentages and expressions are unsupported." } } } }, "example": { "match": { "title": "horses" } } }, "SearchRequest": { "type": "object", "additionalProperties": false, "required": [ "_source" ], "properties": { "query": { "$ref": "#/components/schemas/Query" }, "_source": { "type": "boolean", "enum": [ false ], "description": "Required false. Original JSON source is not retained." }, "from": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 0 }, "size": { "type": "integer", "minimum": 0, "maximum": 100, "default": 10 }, "stored_fields": { "type": "array", "items": { "type": "string", "enum": [ "biblionumber", "title", "author", "subject", "isbn", "keyword_extra" ] }, "default": [] }, "track_total_hits": { "type": "boolean", "enum": [ true ], "default": true } }, "example": { "_source": false, "query": { "match": { "title": "horses" } }, "size": 10, "stored_fields": [ "title", "author" ] } }, "SearchResponse": { "type": "object", "required": [ "took", "timed_out", "_shards", "hits" ], "properties": { "took": { "type": "integer" }, "timed_out": { "type": "boolean" }, "_shards": { "$ref": "#/components/schemas/Shards" }, "hits": { "type": "object", "required": [ "total", "max_score", "hits" ], "properties": { "total": { "type": "object", "required": [ "value", "relation" ], "properties": { "value": { "type": "integer" }, "relation": { "type": "string", "enum": [ "eq" ] } } }, "max_score": { "type": "number", "nullable": true }, "hits": { "type": "array", "items": { "type": "object", "required": [ "_index", "_id", "_score" ], "properties": { "_index": { "type": "string", "enum": [ "biblios" ] }, "_id": { "type": "string" }, "_score": { "type": "number" }, "fields": { "type": "object", "additionalProperties": { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "integer" } ] } } } } } } } } } }, "CountRequest": { "type": "object", "additionalProperties": false, "properties": { "query": { "$ref": "#/components/schemas/Query" } }, "example": { "query": { "match_all": {} } } }, "CountResponse": { "type": "object", "required": [ "count", "_shards" ], "properties": { "count": { "type": "integer" }, "_shards": { "$ref": "#/components/schemas/Shards" } } }, "Error": { "type": "object", "required": [ "error", "status" ], "properties": { "status": { "type": "integer" }, "error": { "type": "object", "required": [ "type", "reason" ], "properties": { "type": { "type": "string" }, "reason": { "type": "string" } } } } }, "Shards": { "type": "object", "required": [ "total", "successful", "skipped", "failed" ], "properties": { "total": { "type": "integer" }, "successful": { "type": "integer" }, "skipped": { "type": "integer" }, "failed": { "type": "integer" } } }, "Capabilities": { "type": "object", "description": "RustSearch identity and bounded API capabilities; not an OpenSearch cluster identity." } } } }