{"id":21496608,"url":"https://github.com/mlibrary/search_api","last_synced_at":"2026-03-19T20:38:00.516Z","repository":{"id":67598774,"uuid":"49744230","full_name":"mlibrary/search_api","owner":"mlibrary","description":"Documentation for the API between Pride and Spectrum","archived":false,"fork":false,"pushed_at":"2022-09-28T16:53:42.000Z","size":20,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-06-04T20:25:17.404Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mlibrary.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2016-01-15T20:51:37.000Z","updated_at":"2022-09-28T16:53:45.000Z","dependencies_parsed_at":"2023-03-09T15:15:17.124Z","dependency_job_id":null,"html_url":"https://github.com/mlibrary/search_api","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/mlibrary/search_api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlibrary%2Fsearch_api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlibrary%2Fsearch_api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlibrary%2Fsearch_api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlibrary%2Fsearch_api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mlibrary","download_url":"https://codeload.github.com/mlibrary/search_api/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlibrary%2Fsearch_api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28811405,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-27T07:41:26.337Z","status":"ssl_error","status_checked_at":"2026-01-27T07:41:08.776Z","response_time":168,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-23T16:17:44.204Z","updated_at":"2026-01-27T09:43:56.772Z","avatar_url":"https://github.com/mlibrary.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Search API\nDocumentation for the API between Pride and Spectrum\n\n## General Notes\n\nWhen the type of a value is STRING it should not contain any HTML. The client is responsible for escaping HTML entities, so any HTML tags in STRING values will be mangled.\n\n## Objects from the Server\n\n### Responses\n\nAll responses from the server use this basic formatting:\n\n```javascript\n{\n  'messages': [\n    // If there are no messages it should be an empty array.\n    // Each message is formatted like this:\n    {\n      'class': 'error' | 'warning' | 'success' | 'info'\n        // 'error'   Something went seriously wrong and either no results were\n        //           produced or the content of this response should be\n        //           considered invalid.\n        //\n        // 'warning' There wasn't a serious problem, but the user should be\n        //           notified of a potential issue (upcoming shutdowns, error\n        //           parsing part of the request, etc).\n        //\n        // 'success' The request was successful and here are details about what\n        //           the server did.\n        //\n        // 'info'    A generic notification, probably unrelated to the search\n        //           result, such as libraries closed due to weather or a new\n        //           service is available.\n\n      'summary': STRING\n        // A short summary of what when wrong. Only a couple of sentences.\n        // Examples: 'Database is not responding' or 'Upcoming shutdown'.\n\n      'details': HTML\n        // A message that can be displayed to the user to give further\n        // explanation or help. The HTML shouldn't have any attributes applied,\n        // just basics tags such as \u003cp\u003e, \u003col\u003e, \u003cul\u003e, \u003cstrong\u003e, \u003cem\u003e, \u003cetc\u003e.\n    }\n  ]\n\n  'request': OBJECT\n    // A copy of the object sent to the server to generate this request.\n    // If no object was sent, this field may be excluded.\n\n  'response': ARRAY | OBJECT\n    // When there is no result of the request or an error occurred the array\n    // or object should empty.\n    // Each request type should only be able to return an array or an object,\n    // not either. Example: datastore queries return an array, while \n}\n```\n\nIn addition to the following more specialized responses, the server must have a URL that which—when hit with a `GET` request—will return a basic response where the `response` field is an array containing a datastore object for every single datastore that the server can run queries against.\n\n#### Datastore Query Responses\n\nThe basic response formatting is extended with the following when the server is responding to a datastore query (a query for records from a datastore).\n\n```javascript\n{\n  'total_available': INT | NULL\n    // How many total records are available for this particular request.\n    // If NULL it is unknown how many are available.\n\n  'datastore': OBJECT\n    // The object for the datastore that is responding.\n    // This is sent in the response since it may have new default facet values\n    // based on the search you just did.\n\n  'new_request': OBJECT\n    // If the client wants to redo the search with a different pagination, they\n    // should send this version of the request object with modified start and\n    // count values.\n    // This is used for things like multisearches, where initially the datastore\n    // object given was a simplified version, but the datastore object returned\n    // by the query is more complicated and may use different formatting.\n\n  // The 'response' field should contain an array of record objects. See below\n  // for how those are formatted.\n}\n```\n\n#### Facet Query Responses\n\nThe basic response formatting is extended with the following when the server is responding to a facet query (a query for more values for a particular facet of a search).\n\n```javascript\n{\n  // All the usual data ('messages', 'request', etc) is included. See above for\n  // how this information is organized.\n\n  'facet': OBJECT\n    // The object for the facet the query was done on.\n    // This is sent in the response since it may have new information based on\n    // the search you just did.\n\n  'total_available': INT | NULL\n    // How many total values are available for this particular facet.\n    // If NULL it is unknown how many are available.\n\n  // The 'response' field should contain an array of facet value objects. See\n  // below for how those are formatted.\n}\n```\n\n### Datastore Objects\n\nDatastore Objects contain all the information necessary to create an interface for a specific search and to generate a query. \"Bento box\" style searches are represented the same way as any other datastore, but they give multiple URLs to send the query to.\n\n```javascript\n{\n  'uid': STRING\n    // A machine readable identifier for this datastore.\n    // Only contains word characters (letters, numbers, underscores).\n\n  'metadata': {\n    'name': STRING\n      // A human readable name for the datastore.\n\n    'short_desc': STRING\n      // A single sentence description of what this datastore contains.\n  }\n\n  'url': URL\n    // The URL where query objects can be sent.\n\n  'sorts': ARRAY\n    // An array containing the various ways the search results can be sorted\n    // such as alphabetical, by relevance, by date, etc.\n    // If there are no sorts available, this array should be empty.\n    // See below for how sort objects are formatted.\n\n  'default_sort': STRING\n    // The 'uid' for the default sort type.\n\n  'fields': [\n    // Array of field objects which look like this:\n    {\n      'uid': STRING\n        // A machine readable identifier for this datastore.\n        // Only contains word characters (letters, numbers, underscores).\n        // There should almost always be a field with a 'uid' of 'all_fields'.\n        // The 'all_fields' is considered the default field which searches\n        // everything.\n\n      'metadata' : {\n        'name': STRING\n          // A human readable name for the field.\n\n        'short_desc': STRING\n          // A one to three sentence description of what this field is.\n      }\n\n      'required': BOOLEAN\n        // Whether or not this field must be set in a query.\n\n      'fixed': BOOLEAN\n        // Whether or not this field can be edited by users.\n\n      'default_value': STRING\n        // The value that this field starts out with.\n        // Normally this is just set to an empty string.\n    }\n  ]\n\n  'facets': ARRAY\n    // An array of facet objects. See below for how those are formatted.\n\n  'settings': [\n    // Array of objects which tell you what settings are available on this\n    // datastore.\n    {\n      'uid': STRING\n        // A machine readable identifier for this particular setting.\n\n      'description':\n        // A human readable description for this setting.\n    }\n  ]\n}\n```\n\n### Facet Objects\n\nFacet objects describe all of the details of a particular facet of a search, give the first set of values for that facet, and give a URL for requesting more values if more are available.\n\n```javascript\n{\n  'uid': STRING\n    // A machine readable identifier for this facet.\n    // Only contains word characters (letters, numbers, underscores).\n\n  'metadata' : {\n    'name': STRING\n      // A human readable name for the facet.\n\n    'short_desc': STRING\n      // A one to three sentence description of what this facet is.\n  }\n\n  'default_value': ANYTHING\n    // The value that will be chosen by default if this facet is not set in\n    // a query.\n\n  'default_sort': STRING\n    // The 'uid' for the default sort type.\n\n  'values': ARRAY\n    // The array contains the first set facet value objects.\n    // See below for how those are formatted.\n\n  'fixed': BOOLEAN\n    // Whether or not this facet can be edited by users.\n\n  'required': BOOLEAN\n    // Whether or not this field must be set to something other than NULL in\n    // a query.\n\n  'more': URL | false\n    // If 'more' is set to a URL, there are more facet values. If it is set\n    // to false then the list of values is complete. A facet value request\n    // object is sent to this URL to get more values for this facet. See below\n    // for how those are formatted.\n\n  'sorts': ARRAY\n    // An array containing the various ways the facet values can be sorted\n    // such as alphabetical, by result count, etc.\n    // If there are no sorts available, this array should be empty.\n    // See below for how sort objects are formatted.\n}\n```\n\n### Facet Value Objects\n\nAll of the information about a particular possible value for a facet.\n\n```javascript\n{\n  'value': ANYTHING\n    // The value that should be sent to the server.\n\n  'name': STRING\n    // A human readable name for this particular value.\n\n  'count': INT\n    // The number of results which have this value.\n    // If not known, do not create the 'count' key/value pair.\n}\n```\n\n### Sort Objects\n\nAll of the information about a possible way to sort facet values or records.\n\n```javascript\n{\n  'uid': STRING\n    // A machine readable identifier for this sort order.\n    // Only contains word characters (letters, numbers, underscores).\n\n  'metadata': {\n    'name': STRING\n      // A human readable name for the sort order.\n\n    'short_desc': STRING\n      // A one to three sentence description of what this sort order is.\n  }\n\n  'group': STRING\n    // If this sort belongs to a group, provide a machine readable (only\n    // alphanumeric and underscores) name that will also be applied to every\n    // other sort object in that group.\n    // Example: if there is an ascending sort and a descending sort, you create\n    // one sort object for each and put the same 'group' value in each object.\n}\n```\n\n### Record Objects\n\nEither a complete set of information about one record, or a partial set with a URL which will return the complete set.\n\n```javascript\n{\n  'type': STRING\n    // A machine readable 'uid' made out of word characters.\n    // Identifies the type of record so the client has a hint about\n    // what fields to expect.\n    // Examples: 'catalog', 'summon', 'deep_blue'\n    // Not used to control rendering, nor is it metadata to show\n    // to the user. It is just to help the client understand what fields\n    // to expect.\n\n  'source': URL\n    // A URL that returns the complete record for this object.\n    // This URL can be used as a unique identifier for this record.\n\n  'complete': BOOLEAN\n    // Whether or not there is more info available on this record.\n\n  'names': [\n    // An array of human readable names for this record.\n    // ALL elements are either HTML or STRING, you can not mix the two.\n    ]\n\n  'names_have_html': BOOLEAN\n    // Whether or not the items in the 'names' array contain HTML.\n    // Used to determine if those values need to be escaped.\n\n  'fields': [\n    // An array of objects that give the information about this record.\n    // Each object is formatted as follows:\n\n    {\n      'uid': STRING\n        // A machine readable identifier for this particular field.\n\n      'name':\n        // A human readable name for this field.\n\n      'value': ANYTHING\n        // Usually this will be a string which is safe to show to users, such as\n        // a title, but it could be anything.\n\n      'value_has_html': BOOLEAN\n        // Whether or not the name contains HTML.\n        // Used to determine if it this value needs to be escaped.\n    }\n  ],\n  'metadata': OBJECT,\n  'header': OBJECT\n}\n```\n\n### Metadata Objects\n\n```json\n{\n  'preview': ARRAY,\n  'medium': ARRAY,\n  'full': ARRAY\n}\n```\n\n### Metadata Item\n\n```javascript\n{\n  'term': STRING,\n  'termPlural': STRING,\n  'description': ARRAY\n}\n```\n\n### Metadata Item Description\n\nFor plain text:\n\n```javascript\n{\n  'text': STRING\n}\n```\n\nFor an href link:\n\n```javascript\n{\n  'text': STRING,\n   'href': STRING\n}\n```\n\nFor a filtered search\n\n```javascript\n{\n  \"text\": STRING,\n  \"search\": {\n    \"type\": STRING,\n    \"scope\": STRING,\n    \"value\": STRING\n  }\n}\n```\n\nFor a fielded query search\n\n```javascript\n{\n  \"text\": STRING,\n  \"search\": {\n    \"type\": STRING,\n    \"scope\": STRING,\n    \"value\": STRING\n  }\n}\n```\n\nWith icon: Use icon names from Design System Iconography.\n\n```javascript\n{\n  \"text\": STRING,\n  \"icon\": STRING\n}\n```\n\n### Header objects\n```javascript\n{\n  \n}\n```\n\n## OBJECTS FROM THE CLIENT\n\n### Queries\n\nIn addition to the following queries, the server has a URL that—when hit with a `GET` request—gives the client a response containing an array of all the datastores the client can run queries against.\n\n#### Datastore Queries\n\nThis object represents a query against a specific datastore. The object must be sent via the `POST` method to the URL specified by the datastore.\n\n```javascript\n{\n  'uid': STRING\n    // A machine readable identifier for the datastore you are querying.\n\n  'request_id': ANYTHING\n    // Some data that the server will not modify.\n    // The 'request' object in the response will have an exact copy of what was\n    // sent in this field.\n    // The 'new_request' object in the response will not contain this value\n    // because the 'new_request' object may not be related to this search such\n    // as in the case of a multisearch search.\n\n  'start': INT\n    // The index of the item you want to start with. 0 is the first index.\n\n  'count': INT\n    // The number of results you are requesting.\n    // Note: the server should never send more results than the client\n    // requested. However, the server may send fewer results than requested.\n\n  'field_tree': OBJECT\n    // A tree that describes the fields being searched, the values to be placed\n    // into those fields, and how to combine them together.\n    // An empty object should be sent when not sending any values.\n    // See below for how this tree is formated\n    \n  'raw_query': STRING\n    // A string representing the raw query.  Client-side parsing is being\n    // phased out in favor of server-side parsing.  The server-side parser\n    // is currently (9/28/2022) used for a limited number of datastores.\n\n  'facets': OBJECT\n    // An object which contains the facets that should be applied to the search.\n    // Each facet is represented as a key/value pair, where the key is the 'uid'\n    // of the facet as defined by the datastore object, and the value is an\n    // array of whatever facet values have been selected by the user. The facet\n    // values can be anything (boolean, string, object, array, number, etc).\n\n  'sort': STRING\n    // The 'uid' for the sort you want to use.\n\n  'settings': OBJECT\n    // An object of additional settings for how you want results formated.\n    // Each settings should be set as a key/value pair, where the key is the\n    // 'uid' for that setting and the value is whatever you want to set it to.\n}\n```\n\n#### Facet Queries\n\nThis object represents a request to get more values for a given facet of a specific search. The object must be sent via the `POST` method to the URL specified by the facet.\n\n```javascript\n{\n  'uid': STRING;\n  // The 'uid' for the facet that you are requesting.\n\n  'query': OBJECT;\n  // The datastore query this facet is associated with.\n  // Should be formatted the same as a datastore query.\n\n  'start': INT\n    // The index of the item you want to start with. 0 is the first index.\n\n  'count': INT\n    // The number of results you are requesting.\n    // Note: the server should never send more results than the client\n    // requested. However, the server may send fewer results than requested.\n\n  'sort': STRING\n    // The 'uid' for the sort you want to use.\n}\n```\n\n### Field Tree Nodes\n\nField trees are represented with a root object which is formatted thusly:\n\n```javascript\n{\n  'type': 'field_boolean' | 'field'   |\n          'value_boolean' | 'tag'     |\n          'literal'       | 'special'\n    // A 'field_boolean' can have children that are 'field_boolean' or 'field'.\n    // A 'field' or 'value_boolean' or 'tag' can have children of any type\n    // except for 'field_boolean' and 'field'.\n    // A 'literal' or 'special' node can not have any children.\n\n\n  'value': STRING\n    // In the case of a 'field_boolean' or 'value_boolean' the literal can be:\n    //   'AND' | 'OR' | 'NOT'\n    // For 'field' type nodes the value is the 'uid' for the field.\n    // For 'literal' or 'special' nodes the value is a string, but in the case\n    // of special nodes the string may have special meaning like it does for *\n    // For 'tag' nodes the value is a string which assigns a special meaning\n    // to its children, like the way + and - are used in some searches to say\n    // that the following is or isn't mandatory.\n\n  'children': ARRAY\n    // The children of this node.\n    // 'AND' and 'OR' booleans assume that all children are joined with that\n    // particular boolean.\n    // 'NOT' booleans assume that all children are joined together with 'AND',\n    // then that group of nodes has the NOT on it. For example, if the children\n    // of a 'NOT' are \"something\", \"else\" and \"blue\" then the serialization is:\n    // NOT(\"something\" AND \"else\" AND \"blue\")\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmlibrary%2Fsearch_api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmlibrary%2Fsearch_api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmlibrary%2Fsearch_api/lists"}