openapi.json

{
  "openapi" : "3.0.0",
  "info" : {
    "title" : "Data Grid Search API",
    "description" : "This is and extensible, pluggable search API for iRODS focused on pluggable Elastic Search indexes.",
    "contact" : {
      "email" : "mike.conway@nih.gov"
    },
    "license" : {
      "name" : "Apache 2.0",
      "url" : "http://www.apache.org/licenses/LICENSE-2.0.html"
    },
    "version" : "1.0.0-oas3"
  },
  "servers" : [ {
    "url" : "http://localhost:8082/v1",
    "description" : "Local dev server"
  } ],
  "security" : [ {
    "BearerAuth" : [ "read", "write" ]
  } ],
  "tags" : [ {
    "name" : "Info",
    "description" : "Endpoints for describing search capabilities and options"
  }, {
    "name" : "Search",
    "description" : "Search on index"
  } ],
  "paths" : {
    "/indexes" : {
      "get" : {
        "tags" : [ "Info" ],
        "summary" : "Find index types supported by this api",
        "description" : "Returns a summary list of the search indexes available at this endpoint",
        "operationId" : "get_indexes",
        "parameters" : [ ],
        "responses" : {
          "200" : {
            "description" : "Successfully retrieved",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/indexes"
                }
              }
            }
          }
        },
        "x-openapi-router-controller" : "swagger_server.controllers.info_controller"
      }
    },
    "/attributes/{index_name}" : {
      "get" : {
        "tags" : [ "Info" ],
        "summary" : "Find search attribute terms for a specific index",
        "description" : "Returns a list of search attribute terms available for specified index",
        "operationId" : "get_index_search_attributes",
        "parameters" : [ {
          "name" : "index_name",
          "in" : "path",
          "required" : true,
          "style" : "simple",
          "explode" : false,
          "schema" : {
            "type" : "string"
          }
        } ],
        "responses" : {
          "200" : {
            "description" : "Successfully retrieved",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/searchAttributes"
                }
              }
            }
          }
        },
        "x-openapi-router-controller" : "swagger_server.controllers.info_controller"
      }
    },
    "/search" : {
      "post" : {
        "tags" : [ "Search" ],
        "summary" : "Generic search on one or all available indexes",
        "description" : "Returns result hits with associated fields and values",
        "operationId" : "generic_search",
        "parameters" : [ {
          "name" : "index_name",
          "in" : "query",
          "required" : true,
          "style" : "form",
          "explode" : true,
          "schema" : {
            "type" : "string"
          }
        }, {
          "name" : "search_query",
          "in" : "query",
          "required" : true,
          "style" : "form",
          "explode" : true,
          "schema" : {
            "type" : "string"
          }
        } ],
        "responses" : {
          "200" : {
            "description" : "Successfully retrieved search result",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/search_data"
                }
              }
            }
          }
        },
        "x-openapi-router-controller" : "swagger_server.controllers.search_controller"
      }
    }
  },
  "components" : {
    "schemas" : {
      "indexes" : {
        "type" : "object",
        "properties" : {
          "id" : {
            "type" : "string",
            "description" : "Unique id that identifies this particular endpoint. Multiple endpoints may be configured to create a search cluster to address distinct indexes"
          },
          "name" : {
            "type" : "string",
            "description" : "Human readable, meaningful name for the search endpoint"
          },
          "info" : {
            "type" : "string",
            "description" : "Documentation about the function of the endpoint"
          },
          "maintainer" : {
            "type" : "string",
            "description" : "Maintainer of the api"
          },
          "contact_email" : {
            "type" : "string",
            "description" : "email address of a support contact",
            "format" : "email"
          },
          "indexes" : {
            "type" : "array",
            "description" : "individually addressable indexes supported by this endpoint",
            "items" : {
              "$ref" : "#/components/schemas/index-schema-description"
            }
          }
        },
        "example" : {
          "indexes" : [ {
            "name" : "name",
            "id" : "id",
            "version" : "version",
            "info" : "info"
          }, {
            "name" : "name",
            "id" : "id",
            "version" : "version",
            "info" : "info"
          } ],
          "name" : "name",
          "id" : "id",
          "maintainer" : "maintainer",
          "info" : "info",
          "contact_email" : ""
        }
      },
      "index-schema-description" : {
        "type" : "object",
        "properties" : {
          "id" : {
            "type" : "string",
            "description" : "Unique identifier for this index type"
          },
          "es_id" : {
            "type" : "string",
            "description" : "elastic search schema mapped by this grid search id"
          },
          "name" : {
            "type" : "string",
            "description" : "Display name for this index type"
          },
          "info" : {
            "type" : "string",
            "description" : "Documentation about this particular index type"
          },
          "version" : {
            "type" : "string",
            "description" : "Version identifier for this endpoint, preferably in semantic versioning style"
          }
        },
        "example" : {
          "name" : "name",
          "id" : "id",
          "version" : "version",
          "info" : "info"
        }
      },
      "searchAttributes" : {
        "type" : "object",
        "properties" : {
          "id" : {
            "type" : "string",
            "description" : "Unique identifier for this index type"
          },
          "name" : {
            "type" : "string",
            "description" : "Display name for this index type"
          },
          "info" : {
            "type" : "string",
            "description" : "Documentation about this particular index type"
          },
          "attributes" : {
            "type" : "array",
            "description" : "array of possible search attributes that can be used to support textual advanced search flags as well as query builder interfaces attribute-by-attribute",
            "items" : {
              "$ref" : "#/components/schemas/index-search-attributes"
            }
          }
        },
        "example" : {
          "name" : "name",
          "attributes" : [ {
            "shortcut_text" : "shortcut_text",
            "attrib_name" : "attrib_name",
            "attrib_example" : "attrib_example",
            "attrib_type" : "date",
            "attrib_path" : "path.to.attrib_name",
            "info" : "info"
          }, {
            "shortcut_text" : "shortcut_text",
            "attrib_name" : "attrib_name",
            "attrib_example" : "attrib_example",
            "attrib_type" : "date",
            "attrib_path" : "path.to.attrib_name",
            "info" : "info"
          } ],
          "id" : "id",
          "info" : "info"
        }
      },
      "index-search-attributes" : {
        "type" : "object",
        "properties" : {
          "attrib_name" : {
            "type" : "string",
            "description" : "attribute name as defined in the base search schema"
          },
          "attrib_type" : {
            "type" : "string",
            "description" : "cue for the type of search attribute in the underlying schema",
            "enum" : [ "date", "string", "int", "float", "boolean" ]
          },
          "attrib_path" : {
            "type" : "string",
            "description" : "Absolute path of the search attribute in nested elastic search indexed document"
          },
          "attrib_example" : {
            "type" : "string",
            "description" : "example for search attribute"
          },
          "info" : {
            "type" : "string",
            "description" : "Documentation about the use of the given search type"
          },
          "shortcut_text" : {
            "type" : "string",
            "description" : "Text shortcut suitable for use in free text advanced search operations, such that Author:XXXX would cause a specific search on the author information in the target index, if not specified it defaults to the attrib_name"
          }
        },
        "example" : {
          "shortcut_text" : "shortcut_text",
          "attrib_name" : "attrib_name",
          "attrib_example" : "attrib_example",
          "attrib_path" : "path.to.attrib_name",
          "attrib_type" : "date",
          "info" : "info"
        }
      },
      "search_data" : {
        "type" : "object",
        "properties" : {
          "index-schema-description" : {
            "$ref" : "#/components/schemas/index-schema-description"
          },
          "search_result" : {
            "type" : "array",
            "items" : {
              "$ref" : "#/components/schemas/search_data_search_result"
            }
          }
        }
      },
      "search_data_linkset" : {
        "type" : "object",
        "properties" : {
          "linkset_title" : {
            "type" : "string",
            "description" : "User friendly title for a link set"
          },
          "linkset_description" : {
            "type" : "string",
            "description" : "Text description of a link set"
          },
          "links" : {
            "type" : "array",
            "items" : {
              "$ref" : "#/components/schemas/search_data_linkset_links"
            }
          }
        }
      },
      "search_data_search_result" : {
        "type" : "object",
        "properties" : {
          "title" : {
            "type" : "string",
            "description" : "Descriptive title for search result"
          },
          "url_link" : {
            "type" : "string",
            "description" : "Resolvable https link to result data location"
          },
          "subtitle" : {
            "type" : "string",
            "description" : "Optional subtitle that can be presented as a highlight, publication info, etc"
          },
          "content_text" : {
            "type" : "string",
            "description" : "Bag of attribute-value paired metadata attached to search hit"
          },
          "links" : {
            "$ref" : "#/components/schemas/search_data_linkset"
          }
        }
      },
      "search_data_linkset_links" : {
        "type" : "object",
        "properties" : {
          "link_text" : {
            "type" : "string",
            "description" : "Text for the link"
          },
          "link_url" : {
            "type" : "string",
            "description" : "URL for the link"
          }
        }
      }
    },
    "securitySchemes" : {
      "BearerAuth" : {
        "type" : "http",
        "scheme" : "bearer",
        "bearerFormat" : "JWT",
        "x-bearerInfoFunc" : "swagger_server.controllers.authorization_controller.check_bearer_auth"
      }
    }
  }
}