search-api.json

{
  "openapi": "3.0.0",
  "servers": [],
  "info": {
    "description": "This defines the baseline for middleTier-to-frontEnd Generic Search APIs for the Grove UI Toolkit.",
    "version": "1.0.0",
    "title": "Grove Middle-tier Generic Search API",
    "license": {
      "name": "Apache-2.0",
      "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
    }
  },
  "paths": {
    "/api/search/{type}": {
      "post": {
        "description": "Search all objects of type `{type}`, returning all available search facets with values as well as matching items. The definition of what the type means is up to the application.",
        "parameters": [
          {
            "name": "type",
            "in": "path",
            "description": "The type against which you are searching. It will typically correspond to a set of searchOptions known to the middle-tier. Convention is to use a pseudo-type of 'all' for generic search-and-discovery applications.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SearchRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Ok",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchFacetsAndResults"
                }
              }
            }
          },
          "401": {
            "$ref": "../common/responses.json#/Responses/Unauthorized"
          }
        }
      }
    },
    "/api/search/{type}/facets": {
      "post": {
        "description": "Search all objects of type `{type}`, returning all available search facets with values. The definition of what the type means is up to the application.",
        "parameters": [
          {
            "name": "type",
            "in": "path",
            "description": "The type against which you are searching. It will typically correspond to a set of searchOptions known to the middle-tier. Convention is to use a pseudo-type of 'all' for generic search-and-discovery applications.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SearchRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Ok",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchFacets"
                }
              }
            }
          },
          "401": {
            "$ref": "../common/responses.json#/Responses/Unauthorized"
          }
        }
      }
    },
    "/api/search/{type}/results": {
      "post": {
        "description": "Search all objects of type `{type}`, returning matching items. The definition of what the type means is up to the application.",
        "parameters": [
          {
            "name": "type",
            "in": "path",
            "description": "The type against which you are searching. It will typically correspond to a set of searchOptions known to the middle-tier. Convention is to use a pseudo-type of 'all' for generic search-and-discovery applications.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SearchRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Ok",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResults"
                }
              }
            }
          },
          "401": {
            "$ref": "../common/responses.json#/Responses/Unauthorized"
          }
        }
      }
    },
    "/suggest/{type}" : {
      "post" : {
        "description" : "Provide suggestions for search values for type `{type}` across all search facets, and other sources for the type, taking provided constraints into consideration",
        "parameters" : [ {
          "name" : "type",
          "in" : "path",
          "description" : "The type against which you are searching.",
          "required" : true,
          "style" : "simple",
          "explode" : false,
          "schema" : {
            "type" : "string"
          }
        }],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SuggestRequest"
              }
            }
          }
        },
        "responses" : {
          "200" : {
            "description" : "Ok",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/SuggestResult"
                }
              }
            }
          },
          "401" : {
            "$ref" : "../common/responses.json#/Responses/Unauthorized"
          }
        }
      }
    },
    "/suggest/{type}/facets/{facet}" : {
      "post" : {
        "description" : "Provide suggestions for search values for facet `{facet}` of type `{type}`, taking provided constraints into consideration.",
        "parameters" : [ {
          "name" : "type",
          "in" : "path",
          "description" : "The type against which you are searching.",
          "required" : true,
          "style" : "simple",
          "explode" : false,
          "schema" : {
            "type" : "string"
          }
        }, {
          "name" : "facet",
          "in" : "path",
          "description" : "The facet name against which the suggestions will be based..",
          "required" : true,
          "style" : "simple",
          "explode" : false,
          "schema" : {
            "type" : "string"
          }
        }],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SuggestRequest"
              }
            }
          }
        },
        "responses" : {
          "200" : {
            "description" : "Ok",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/SuggestResult"
                }
              }
            }
          },
          "401" : {
            "$ref" : "../common/responses.json#/Responses/Unauthorized"
          }
        }
      }
    }
  },
  "security": [],
  "components": {
    "links": {},
    "callbacks": {},
    "schemas": {
      "SearchRequest": {
        "type": "object",
        "properties": {
          "filters": {
            "$ref": "#/components/schemas/CombinedFilter"
          },
          "options": {
            "type": "object",
            "properties": {
              "start": {
                "type": "integer",
                "description": "result to start on for pagination",
                "minimum": 1,
                "default": 1
              },
              "pageLength": {
                "type": "integer",
                "description": "number of results to include for one page",
                "minimum": 1,
                "default": 10
              }
            },
            "additionalProperties": true
          }
        }
      },
      "SuggestRequest": {
        "type": "object",
        "properties": {
          "filters": {
            "$ref": "#/components/schemas/CombinedFilter"
          },
          "options": {
            "type": "object",
            "properties": {
              "partial": {
                "type": "string",
                "description": "partial value used as 'seed' for suggestion values",
                "default": ""
              },
              "start": {
                "type": "integer",
                "description": "index of first suggestion value to return",
                "minimum": 1,
                "default": 1
              },
              "pageLength": {
                "type": "integer",
                "description": "number of suggestion values to return",
                "minimum": 1,
                "default": 10
              }
            },
            "additionalProperties": true
          }
        }
      },
      "CombinedFilter": {
        "description": "A recursive structure of filters, including CustomFilters defined by specific applications.",
        "oneOf": [
          {
            "$ref": "#/components/schemas/AndFilter"
          },
          {
            "$ref": "#/components/schemas/OrFilter"
          },
          {
            "$ref": "#/components/schemas/NotFilter"
          },
          {
            "$ref": "#/components/schemas/NearFilter"
          },
          {
            "$ref": "#/components/schemas/SelectionFilter"
          },
          {
            "$ref": "#/components/schemas/RangeFilter"
          },
          {
            "$ref": "#/components/schemas/QueryTextFilter"
          },
          {
            "$ref": "#/components/schemas/CustomFilter"
          }
        ],
        "example": {
          "and": [
            {
              "type": "queryText",
              "value": "foo AND bar"
            },
            {
              "type": "selection",
              "constraint": "firstName",
              "value": [
                "Geert",
                {
                  "not": "Patrick"
                }
              ],
              "mode": "and"
            },
            {
              "type": "selection",
              "constraint": "active",
              "value": true
            },
            {
              "type": "range",
              "constraint": "age",
              "value": {
                "ge": 20,
                "ne": 99
              }
            },
            {
              "type": "selection",
              "constraint": "eyeColor",
              "value": [
                "blue",
                "brown"
              ],
              "mode": "or"
            },
            {
              "or": [
                {
                  "type": "selection",
                  "constraint": "occupationCategory",
                  "value": "software"
                },
                {
                  "and": [
                    {
                      "type": "selection",
                      "constraint": "occupationCategory",
                      "value": "IT"
                    },
                    {
                      "not": {
                        "type": "selection",
                        "constraint": "occupationCategory",
                        "mode": "or",
                        "value": [
                          "marketing",
                          "support"
                        ]
                      }
                    }
                  ]
                }
              ]
            },
            {
              "near": {
                "filters": [
                  {
                    "type": "queryText",
                    "value": "Patrick"
                  },
                  {
                    "type": "queryText",
                    "value": "McElwee"
                  }
                ],
                "distance": 10
              }
            }
          ]
        }
      },
      "TypedFilter": {
        "description": "A parent type for all typed filters, which are not recursive, and which connect values to constraints, according to typed semantic.",
        "type": "object",
        "discriminator": {
          "propertyName": "type",
          "mapping": {
            "selection": "#/components/schemas/SelectionFilter",
            "range": "#/components/schemas/RangeFilter",
            "queryText": "#/components/schemas/QueryTextFilter"
          }
        },
        "properties": {
          "type": {
            "type": "string"
          },
          "value": {
            "$ref": "#/components/schemas/AnyValue"
          },
          "constraint": {
            "type": "string"
          }
        },
        "additionalProperties": true,
        "required": [
          "type",
          "value"
        ]
      },
      "SelectionFilter": {
        "description": "A filter connecting discrete selected values to a constraint. Values can optionally be negated.",
        "example": {
          "type": "selection",
          "constraint": "classification",
          "mode": "or",
          "value": [
            {
              "not": "mammal"
            },
            "platypus",
            "kangaroo"
          ]
        },
        "allOf": [
          {
            "$ref": "#/components/schemas/TypedFilter"
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "enum": [
                  "selection"
                ]
              },
              "mode": {
                "type": "string",
                "default": "and",
                "enum": [
                  "and",
                  "or"
                ]
              },
              "value": {
                "type": "array",
                "items": {
                  "oneOf": [
                    {
                      "type": "number"
                    },
                    {
                      "type": "string"
                    },
                    {
                      "type": "boolean"
                    },
                    {
                      "$ref": "#/components/schemas/NegatedSelection"
                    }
                  ]
                }
              }
            }
          }
        ]
      },
      "NegatedSelection": {
        "description": "A helper type showing a simple negated selection.",
        "type": "object",
        "properties": {
          "not": {
            "oneOf": [
              {
                "type": "number"
              },
              {
                "type": "string"
              },
              {
                "type": "boolean"
              }
            ]
          }
        },
        "required": [
          "not"
        ]
      },
      "RangeFilter": {
        "description": "A filter connecting a range of selected values to a constraint. Allows operators `gt` (greater-than), `ge` (greater-than-or-equal-to), `lt` (less-than), `le` (less-than-or-equal-to), `eq` (equal-to), and `ne` (not-equal-to).",
        "allOf": [
          {
            "$ref": "#/components/schemas/TypedFilter"
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "enum": [
                  "range"
                ]
              },
              "value": {
                "type": "object",
                "properties": {
                  "gt": {
                    "oneOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "number"
                      },
                      {
                        "type": "boolean"
                      }
                    ]
                  },
                  "ge": {
                    "oneOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "number"
                      },
                      {
                        "type": "boolean"
                      }
                    ]
                  },
                  "lt": {
                    "oneOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "number"
                      },
                      {
                        "type": "boolean"
                      }
                    ]
                  },
                  "le": {
                    "oneOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "number"
                      },
                      {
                        "type": "boolean"
                      }
                    ]
                  },
                  "eq": {
                    "oneOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "number"
                      },
                      {
                        "type": "boolean"
                      }
                    ]
                  },
                  "ne": {
                    "oneOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "number"
                      },
                      {
                        "type": "boolean"
                      }
                    ]
                  }
                }
              }
            }
          }
        ],
        "example": {
          "type": "range",
          "constraint": "age",
          "value": {
            "ge": 21,
            "lt": 30
          }
        }
      },
      "QueryTextFilter": {
        "description": "A filter representing query text.",
        "allOf": [
          {
            "$ref": "#/components/schemas/TypedFilter"
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "enum": [
                  "queryText"
                ]
              },
              "value": {
                "type": "string"
              }
            }
          }
        ],
        "example": {
          "type": "queryText",
          "value": "foo AND bar"
        }
      },
      "CustomFilter": {
        "description": "A new filter type, created as an extension to core filter types.",
        "allOf": [
          {
            "$ref": "#/components/schemas/TypedFilter"
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  {
                    "not": "selection"
                  },
                  {
                    "not": "range"
                  },
                  {
                    "not": "queryText"
                  }
                ]
              }
            }
          }
        ]
      },
      "AndFilter": {
        "description": "A filter representing an AND between child filters.",
        "type": "object",
        "properties": {
          "and": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CombinedFilter"
            }
          }
        },
        "required": [
          "and"
        ]
      },
      "OrFilter": {
        "description": "A filter representing an OR between child filters.",
        "type": "object",
        "properties": {
          "or": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CombinedFilter"
            }
          }
        },
        "required": [
          "or"
        ]
      },
      "NotFilter": {
        "description": "A negation of one child filter.",
        "type": "object",
        "properties": {
          "not": {
            "$ref": "#/components/schemas/CombinedFilter"
          }
        },
        "required": [
          "not"
        ]
      },
      "NearFilter": {
        "description": "A filter representing a NEAR between child filters.",
        "type": "object",
        "properties": {
          "filters": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CombinedFilter"
            }
          },
          "distance": {
            "type": "number",
            "default": 10
          }
        },
        "required": [
          "filters"
        ]
      },
      "SearchFacetsAndResults": {
        "type": "object",
        "properties": {
          "total": {
            "type": "integer"
          },
          "start": {
            "type": "integer"
          },
          "pageLength": {
            "type": "integer"
          },
          "facets": {
            "type": "object",
            "additionalProperties": {
              "$ref": "#/components/schemas/SearchFacet"
            }
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SearchResult"
            }
          },
          "metrics": {
            "$ref": "#/components/schemas/SearchMetrics"
          }
        },
        "required": [
          "total",
          "facets",
          "results",
          "metrics"
        ],
        "additionalProperties": true
      },
      "SearchResults": {
        "type": "object",
        "properties": {
          "total": {
            "type": "integer"
          },
          "start": {
            "type": "integer"
          },
          "pageLength": {
            "type": "integer"
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SearchResult"
            }
          },
          "metrics": {
            "$ref": "#/components/schemas/SearchMetrics"
          }
        },
        "required": [
          "total",
          "results",
          "metrics"
        ],
        "additionalProperties": true
      },
      "SearchResult": {
        "type": "object",
        "description": "A single search result. Either uri or id is required.",
        "properties": {
          "uri": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "score": {
            "type": "number"
          },
          "extracted": {
            "type": "object",
            "properties": {
              "kind": {
                "type": "string"
              },
              "content": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/AnyValue"
                }
              }
            }
          },
          "matches": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "match-text": {
                  "type": "array",
                  "items": {
                    "oneOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "object",
                        "properties": {
                          "highlight": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "highlight"
                        ]
                      }
                    ]
                  }
                },
                "path": {
                  "type": "string"
                }
              },
              "required": [
                "match-text"
              ]
            }
          }
        },
        "required": [
          "uri",
          "id"
        ],
        "additionalProperties": true
      },
      "SearchFacets": {
        "type": "object",
        "properties": {
          "facets": {
            "type": "object",
            "additionalProperties": {
              "$ref": "#/components/schemas/SearchFacet"
            }
          },
          "metrics": {
            "$ref": "#/components/schemas/SearchMetrics"
          }
        },
        "required": [
          "facets"
        ],
        "additionalProperties": true
      },
      "SearchFacet": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string"
          },
          "facetValues": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FacetValue"
            }
          }
        },
        "required": [
          "facetValues"
        ],
        "additionalProperties": true
      },
      "FacetValue": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "count": {
            "type": "integer"
          },
          "value": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "boolean"
              }
            ]
          }
        },
        "required": [
          "name",
          "count",
          "value"
        ]
      },
      "SearchMetrics": {
        "type": "object",
        "properties": {
          "total-time": {
            "type": "string"
          }
        },
        "additionalProperties": true
      },
      "AnyValue": {},
      "SuggestResult" : {
        "type" : "object",
        "properties" : {
          "suggestions" : {
            "type" : "array",
            "items" : {
              "type" : "string"
            }
          }
        }
      }
    },
    "securitySchemes": {}
  }
}