https://github.com/mlibrary/search_api

Documentation for the API between Pride and Spectrum
https://github.com/mlibrary/search_api

Last synced: 3 months ago
JSON representation

Documentation for the API between Pride and Spectrum

Host: GitHub
URL: https://github.com/mlibrary/search_api
Owner: mlibrary
Created: 2016-01-15T20:51:37.000Z (over 10 years ago)
Default Branch: master
Last Pushed: 2022-09-28T16:53:42.000Z (over 3 years ago)
Last Synced: 2025-06-04T20:25:17.404Z (about 1 year ago)
Size: 19.5 KB
Stars: 1
Watchers: 2
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md

Awesome Lists containing this project

README

# Search API
Documentation for the API between Pride and Spectrum

## General Notes

When 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.

## Objects from the Server

### Responses

All responses from the server use this basic formatting:

```javascript
{
'messages': [
// If there are no messages it should be an empty array.
// Each message is formatted like this:
{
'class': 'error' | 'warning' | 'success' | 'info'
// 'error' Something went seriously wrong and either no results were
// produced or the content of this response should be
// considered invalid.
//
// 'warning' There wasn't a serious problem, but the user should be
// notified of a potential issue (upcoming shutdowns, error
// parsing part of the request, etc).
//
// 'success' The request was successful and here are details about what
// the server did.
//
// 'info' A generic notification, probably unrelated to the search
// result, such as libraries closed due to weather or a new
// service is available.

'summary': STRING
// A short summary of what when wrong. Only a couple of sentences.
// Examples: 'Database is not responding' or 'Upcoming shutdown'.

'details': HTML
// A message that can be displayed to the user to give further
// explanation or help. The HTML shouldn't have any attributes applied,
// just basics tags such as

, , .
}
]

'request': OBJECT
// A copy of the object sent to the server to generate this request.
// If no object was sent, this field may be excluded.

'response': ARRAY | OBJECT
// When there is no result of the request or an error occurred the array
// or object should empty.
// Each request type should only be able to return an array or an object,
// not either. Example: datastore queries return an array, while
}
```

In 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.

#### Datastore Query Responses

The basic response formatting is extended with the following when the server is responding to a datastore query (a query for records from a datastore).

```javascript
{
'total_available': INT | NULL
// How many total records are available for this particular request.
// If NULL it is unknown how many are available.

'datastore': OBJECT
// The object for the datastore that is responding.
// This is sent in the response since it may have new default facet values
// based on the search you just did.

'new_request': OBJECT
// If the client wants to redo the search with a different pagination, they
// should send this version of the request object with modified start and
// count values.
// This is used for things like multisearches, where initially the datastore
// object given was a simplified version, but the datastore object returned
// by the query is more complicated and may use different formatting.

// The 'response' field should contain an array of record objects. See below
// for how those are formatted.
}
```

#### Facet Query Responses

The 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).

```javascript
{
// All the usual data ('messages', 'request', etc) is included. See above for
// how this information is organized.

'facet': OBJECT
// The object for the facet the query was done on.
// This is sent in the response since it may have new information based on
// the search you just did.

'total_available': INT | NULL
// How many total values are available for this particular facet.
// If NULL it is unknown how many are available.

// The 'response' field should contain an array of facet value objects. See
// below for how those are formatted.
}
```

### Datastore Objects

Datastore 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.

```javascript
{
'uid': STRING
// A machine readable identifier for this datastore.
// Only contains word characters (letters, numbers, underscores).

'metadata': {
'name': STRING
// A human readable name for the datastore.

'short_desc': STRING
// A single sentence description of what this datastore contains.
}

'url': URL
// The URL where query objects can be sent.

'sorts': ARRAY
// An array containing the various ways the search results can be sorted
// such as alphabetical, by relevance, by date, etc.
// If there are no sorts available, this array should be empty.
// See below for how sort objects are formatted.

'default_sort': STRING
// The 'uid' for the default sort type.

'fields': [
// Array of field objects which look like this:
{
'uid': STRING
// A machine readable identifier for this datastore.
// Only contains word characters (letters, numbers, underscores).
// There should almost always be a field with a 'uid' of 'all_fields'.
// The 'all_fields' is considered the default field which searches
// everything.

'metadata' : {
'name': STRING
// A human readable name for the field.

'short_desc': STRING
// A one to three sentence description of what this field is.
}

'required': BOOLEAN
// Whether or not this field must be set in a query.

'fixed': BOOLEAN
// Whether or not this field can be edited by users.

'default_value': STRING
// The value that this field starts out with.
// Normally this is just set to an empty string.
}
]

'facets': ARRAY
// An array of facet objects. See below for how those are formatted.

'settings': [
// Array of objects which tell you what settings are available on this
// datastore.
{
'uid': STRING
// A machine readable identifier for this particular setting.

'description':
// A human readable description for this setting.
}
]
}
```

### Facet Objects

Facet 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.

```javascript
{
'uid': STRING
// A machine readable identifier for this facet.
// Only contains word characters (letters, numbers, underscores).

'metadata' : {
'name': STRING
// A human readable name for the facet.

'short_desc': STRING
// A one to three sentence description of what this facet is.
}

'default_value': ANYTHING
// The value that will be chosen by default if this facet is not set in
// a query.

'default_sort': STRING
// The 'uid' for the default sort type.

'values': ARRAY
// The array contains the first set facet value objects.
// See below for how those are formatted.

'fixed': BOOLEAN
// Whether or not this facet can be edited by users.

'required': BOOLEAN
// Whether or not this field must be set to something other than NULL in
// a query.

'more': URL | false
// If 'more' is set to a URL, there are more facet values. If it is set
// to false then the list of values is complete. A facet value request
// object is sent to this URL to get more values for this facet. See below
// for how those are formatted.

'sorts': ARRAY
// An array containing the various ways the facet values can be sorted
// such as alphabetical, by result count, etc.
// If there are no sorts available, this array should be empty.
// See below for how sort objects are formatted.
}
```

### Facet Value Objects

All of the information about a particular possible value for a facet.

```javascript
{
'value': ANYTHING
// The value that should be sent to the server.

'name': STRING
// A human readable name for this particular value.

'count': INT
// The number of results which have this value.
// If not known, do not create the 'count' key/value pair.
}
```

### Sort Objects

All of the information about a possible way to sort facet values or records.

```javascript
{
'uid': STRING
// A machine readable identifier for this sort order.
// Only contains word characters (letters, numbers, underscores).

'metadata': {
'name': STRING
// A human readable name for the sort order.

'short_desc': STRING
// A one to three sentence description of what this sort order is.
}

'group': STRING
// If this sort belongs to a group, provide a machine readable (only
// alphanumeric and underscores) name that will also be applied to every
// other sort object in that group.
// Example: if there is an ascending sort and a descending sort, you create
// one sort object for each and put the same 'group' value in each object.
}
```

### Record Objects

Either a complete set of information about one record, or a partial set with a URL which will return the complete set.

```javascript
{
'type': STRING
// A machine readable 'uid' made out of word characters.
// Identifies the type of record so the client has a hint about
// what fields to expect.
// Examples: 'catalog', 'summon', 'deep_blue'
// Not used to control rendering, nor is it metadata to show
// to the user. It is just to help the client understand what fields
// to expect.

'source': URL
// A URL that returns the complete record for this object.
// This URL can be used as a unique identifier for this record.

'complete': BOOLEAN
// Whether or not there is more info available on this record.

'names': [
// An array of human readable names for this record.
// ALL elements are either HTML or STRING, you can not mix the two.
]

'names_have_html': BOOLEAN
// Whether or not the items in the 'names' array contain HTML.
// Used to determine if those values need to be escaped.

'fields': [
// An array of objects that give the information about this record.
// Each object is formatted as follows:

{
'uid': STRING
// A machine readable identifier for this particular field.

'name':
// A human readable name for this field.

'value': ANYTHING
// Usually this will be a string which is safe to show to users, such as
// a title, but it could be anything.

'value_has_html': BOOLEAN
// Whether or not the name contains HTML.
// Used to determine if it this value needs to be escaped.
}
],
'metadata': OBJECT,
'header': OBJECT
}
```

### Metadata Objects

```json
{
'preview': ARRAY,
'medium': ARRAY,
'full': ARRAY
}
```

### Metadata Item

```javascript
{
'term': STRING,
'termPlural': STRING,
'description': ARRAY
}
```

### Metadata Item Description

For plain text:

```javascript
{
'text': STRING
}
```

For an href link:

```javascript
{
'text': STRING,
'href': STRING
}
```

For a filtered search

```javascript
{
"text": STRING,
"search": {
"type": STRING,
"scope": STRING,
"value": STRING
}
}
```

For a fielded query search

```javascript
{
"text": STRING,
"search": {
"type": STRING,
"scope": STRING,
"value": STRING
}
}
```

With icon: Use icon names from Design System Iconography.

```javascript
{
"text": STRING,
"icon": STRING
}
```

### Header objects
```javascript
{

}
```

## OBJECTS FROM THE CLIENT

### Queries

In 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.

#### Datastore Queries

This object represents a query against a specific datastore. The object must be sent via the `POST` method to the URL specified by the datastore.

```javascript
{
'uid': STRING
// A machine readable identifier for the datastore you are querying.

'request_id': ANYTHING
// Some data that the server will not modify.
// The 'request' object in the response will have an exact copy of what was
// sent in this field.
// The 'new_request' object in the response will not contain this value
// because the 'new_request' object may not be related to this search such
// as in the case of a multisearch search.

'start': INT
// The index of the item you want to start with. 0 is the first index.

'count': INT
// The number of results you are requesting.
// Note: the server should never send more results than the client
// requested. However, the server may send fewer results than requested.

'field_tree': OBJECT
// A tree that describes the fields being searched, the values to be placed
// into those fields, and how to combine them together.
// An empty object should be sent when not sending any values.
// See below for how this tree is formated

'raw_query': STRING
// A string representing the raw query. Client-side parsing is being
// phased out in favor of server-side parsing. The server-side parser
// is currently (9/28/2022) used for a limited number of datastores.

'facets': OBJECT
// An object which contains the facets that should be applied to the search.
// Each facet is represented as a key/value pair, where the key is the 'uid'
// of the facet as defined by the datastore object, and the value is an
// array of whatever facet values have been selected by the user. The facet
// values can be anything (boolean, string, object, array, number, etc).

'sort': STRING
// The 'uid' for the sort you want to use.

'settings': OBJECT
// An object of additional settings for how you want results formated.
// Each settings should be set as a key/value pair, where the key is the
// 'uid' for that setting and the value is whatever you want to set it to.
}
```

#### Facet Queries

This 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.

```javascript
{
'uid': STRING;
// The 'uid' for the facet that you are requesting.

'query': OBJECT;
// The datastore query this facet is associated with.
// Should be formatted the same as a datastore query.

'start': INT
// The index of the item you want to start with. 0 is the first index.

'count': INT
// The number of results you are requesting.
// Note: the server should never send more results than the client
// requested. However, the server may send fewer results than requested.

'sort': STRING
// The 'uid' for the sort you want to use.
}
```

### Field Tree Nodes

Field trees are represented with a root object which is formatted thusly:

```javascript
{
'type': 'field_boolean' | 'field' |
'value_boolean' | 'tag' |
'literal' | 'special'
// A 'field_boolean' can have children that are 'field_boolean' or 'field'.
// A 'field' or 'value_boolean' or 'tag' can have children of any type
// except for 'field_boolean' and 'field'.
// A 'literal' or 'special' node can not have any children.

'value': STRING
// In the case of a 'field_boolean' or 'value_boolean' the literal can be:
// 'AND' | 'OR' | 'NOT'
// For 'field' type nodes the value is the 'uid' for the field.
// For 'literal' or 'special' nodes the value is a string, but in the case
// of special nodes the string may have special meaning like it does for *
// For 'tag' nodes the value is a string which assigns a special meaning
// to its children, like the way + and - are used in some searches to say
// that the following is or isn't mandatory.

'children': ARRAY
// The children of this node.
// 'AND' and 'OR' booleans assume that all children are joined with that
// particular boolean.
// 'NOT' booleans assume that all children are joined together with 'AND',
// then that group of nodes has the NOT on it. For example, if the children
// of a 'NOT' are "something", "else" and "blue" then the serialization is:
// NOT("something" AND "else" AND "blue")
}
```

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/mlibrary/search_api

Awesome Lists containing this project

README