java.lang.Object
- nzilbb.labbcat.server.api.APIRequestHandler
- - nzilbb.labbcat.server.api.Store

Direct Known Subclasses:

Store
```
public class Store
extends APIRequestHandler
```
Endpoints starting /api/store/… provide an HTTP-based API for access to GraphStore functions.
These endpoints all work for GET HTTP requests and return a JSON response with the same standard envelope structure:

title

(string) The title of the LaBB-CAT instance.

version

(string) The version of the LaBB-CAT instance

code

(int) 0 if the request was successful, 1 if there was a problem

messages

An array of message strings.

errors

An array of error message strings.

model

The result of the request, which may be a JSON object, JSON array, or a simple type.

e.g. the response to http://localhost:8080/labbcat/api/store/getLayer?id=word might be:
```
{
    "title":"LaBB-CAT",
    "version":"20200129.1901",
    "code":0,
    "errors":[],
    "messages":[],
    "model":{
        "id":"word",
        "parentId":"turns",
        "description":"Word tokens",
        "alignment":2,
        "peers":true,
        "peersOverlap":false,
        "parentIncludes":true,
        "saturated":false,
        "type":"string",
        "validLabels":{},
        "category":null
    }
}
```
If the Accept-Language request header is set, the server will endeavor to localize messages to the specified language.
User authorization for password-protected instances of LaBB-CAT uses the 'Basic' HTTP authentication scheme. This involves sending an Authorization request header of the form Basic TTTTTTTT, where TTTTTTTT is an authentication token formed by base64-encoding a string of the form username:password
- /api/store/getId
  
  Gets the store's ID.
  
  Returns:
  
  The annotation store's ID.
- /api/store/getLayerIds
  
  Gets a list of layer IDs (annotation 'types').
  
  Returns:
  
  A list of layer IDs.
- /api/store/getLayers
  
  Gets a list of layer definitions.
  
  Returns:
  
  A list of layer definitions.
- /api/store/getSchema
  
  Gets the layer schema.
  
  Returns:
  
  A schema defining the layers and how they relate to each other.
- /api/store/getLayer
  
  Gets a layer definition.
  
  Parameters:
  
  id - ID of the layer to get the definition for.
  
  Returns:
  
  The definition of the given layer.
LaBB-CAT extends the Layer.validLabels funcionality by supporting an alternative layer attribute: validLabelsDefinition, which is an array of label definitions, each definition being a map of string to string or integer. Each label definition is expected to have the following attributes:

label

what the underlying label is in LaBB-CAT (i.e. the DISC label, for a DISC layer)

legend

the symbol on the label helper or in the transcript, for the label (e.g. the IPA version of the label) - if there's no legend specified, then there's no option on the label helper (so that type-able consonants like p, b, t, d etc. don't take up space on the label helper)

description

tool-tip text that appears if you hover the mouse over the IPA symbol in the helper

category

the broad category of the symbol, for organizing the layout of the helper

subcategory

the narrower category of the symbol, for listing subgroups of symbols together

display_order

the order to process/list the labels in

validLabelsDefinition is returned if there is a hierarchical set of options defined. Either way, validLabels (specifying the valid labels and their 'legend' values) is always returned.
- /api/store/getCorpusIds
  
  Gets a list of corpus IDs.
  
  Returns:
  
  A list of corpus IDs.
- /api/store/getParticipantIds
  
  Gets a list of participant IDs.
  
  Returns:
  
  A list of participant IDs.
- /api/store/getParticipant
  
  Gets the participant record specified by the given identifier.
  
  Parameters:
  
  id - The ID of the participant, which could be their name or their database annotation ID.
  
  layerIds - The IDs of the participant attribute layers to load, passed by specifying the layerIds multiple times, once for each layer, or absent if only participant data is required.
  
  Returns:
  
  An annotation representing the participant, or null if the participant was not found.
- /api/store/countMatchingParticipantIds
  
  Counts the number of participants that match a particular pattern.
  Parameters:
  expression - An expression that determines which participants match.
  The expression language is currently not well defined, but expressions such as the following can be used:
  
  /Ada.+/.test(id)
  
  labels('corpus').includes('CC')
  
  labels('participant_languages').includes('en')
  
  labels('transcript_language').includes('en')
  
  !/Ada.+/.test(id) && first('corpus').label == 'CC'
  
  all('transcript_rating').length > 2
  
  all('participant_rating').length = 0
  
  !annotators('transcript_rating').includes('labbcat')
  
  first('participant_gender').label == 'NA'
  Returns:
  
  The number of matching participants.
- /api/store/getMatchingParticipantIds
  
  Gets a list of IDs of participants that match a particular pattern.
  Parameters:
  expression - An expression that determines which participants match.
  The expression language is currently not well defined, but expressions such as the following can be used:
  
  /Ada.+/.test(id)
  
  labels('corpus').includes('CC')
  
  labels('participant_languages').includes('en')
  
  labels('transcript_language').includes('en')
  
  !/Ada.+/.test(id) && first('corpus').label == 'CC'
  
  all('transcript_rating').length > 2
  
  all('participant_rating').length = 0
  
  !annotators('transcript_rating').includes('labbcat')
  
  first('participant_gender').label == 'NA'
  pageLength (Optional) - The maximum number of IDs to return, or absent to return all.
  
  pageNumber (Optional) - The zero-based page number to return, or absent to return the first page.
  
  Returns:
  
  A list of participant IDs.
- /api/store/getTranscriptIds
  
  Gets a list of transcript IDs.
  
  Returns:
  
  A list of transcript IDs.
- /api/store/getTranscriptIdsInCorpus
  
  Gets a list of transcript IDs in the given corpus.
  
  Parameters:
  
  id - A corpus ID.
  
  Returns:
  
  A list of transcript IDs.
- /api/store/getTranscriptIdsWithParticipant
  
  Gets a list of IDs of transcripts that include the given participant.
  
  Parameters:
  
  id - A participant ID.
  
  Returns:
  
  A list of transcript IDs.
- /api/store/countMatchingTranscriptIds
  
  Counts the number of transcripts that match a particular pattern.
  Parameters:
  expression - An expression that determines which transcripts match.
  The expression language is currently not well defined, but expressions such as the following can be used:
  
  /Ada.+/.test(id)
  
  labels('participant').includes('Robert')
  
  ['CC', 'IA', 'MU'].includes(first('corpus').label)
  
  first('episode').label == 'Ada Aitcheson'
  
  first('transcript_scribe').label == 'Robert'
  
  first('participant_languages').label == 'en'
  
  first('noise').label == 'bell'
  
  labels('transcript_languages').includes('en')
  
  labels('participant_languages').includes('en')
  
  labels('noise').includes('bell')
  
  all('transcript_languages').length gt; 1
  
  all('participant_languages').length gt; 1
  
  all('word').length > 100
  
  annotators('transcript_rating').includes('Robert')
  
  !/Ada.+/.test(id) && first('corpus').label == 'CC' && labels('participant').includes('Robert')
  Returns:
  
  The number of matching transcripts.
- /api/store/getMatchingTranscriptIds
  
  Gets a list of IDs of transcripts that match a particular pattern.
  
  The results can be exhaustive, by omitting pageLength and pageNumber, or they can be a subset (a 'page') of results, by given pageLength and pageNumber values.
  
  The order of the list can be specified. If ommitted, the transcripts are listed in ID order.
  Parameters:
  expression - An expression that determines which transcripts match.
  The expression language is currently not well defined, but expressions such as the following can be used:
  
  /Ada.+/.test(id)
  
  labels('participant').includes('Robert')
  
  ['CC', 'IA', 'MU'].includes(first('corpus').label)
  
  first('episode').label == 'Ada Aitcheson'
  
  first('transcript_scribe').label == 'Robert'
  
  first('participant_languages').label == 'en'
  
  first('noise').label == 'bell'
  
  labels('transcript_languages').includes('en')
  
  labels('participant_languages').includes('en')
  
  labels('noise').includes('bell')
  
  all('transcript_languages').length gt; 1
  
  all('participant_languages').length gt; 1
  
  all('word').length > 100
  
  annotators('transcript_rating').includes('Robert')
  
  !/Ada.+/.test(id) && first('corpus').label == 'CC' && labels('participant').includes('Robert')
  pageLength (Optional) - The maximum number of IDs to return, or absent to return all.
  
  pageNumber (Optional) - The zero-based page number to return, or absent to return the first page.
  
  order (Optional) - The ordering for the list of IDs, a string containing a comma-separated list of expressions, which may be appended by " ASC" or " DESC", or absent for transcript ID order.
  
  Returns:
  
  A list of transcript IDs.
- /api/store/countMatchingAnnotations
  
  Counts the number of annotations that match a particular pattern.
  Parameters:
  expression - An expression that determines which participants match.
  The expression language is currently not well defined, but expressions such as the following can be used:
  
  id = 'ew_0_456'
  
  !/th[aeiou].+/.test(label)
  
  layer.id == 'orthography' && first('participant').label == 'Robert' && first('utterance').start.offset == 12.345
  
  graph.id == 'AdaAicheson-01.trs' & layer.id == 'orthography' & start.offset > 10.5
  
  NB all expressions must match by either id or layer.id.
  Returns:
  
  The number of matching annotations.
- /api/store/getMatchingAnnotations
  
  Gets a list of annotations that match a particular pattern.
  Parameters:
  expression - An expression that determines which transcripts match.
  The expression language is currently not well defined, but expressions such as the following can be used:
  
  id = 'ew_0_456'
  
  !/th[aeiou].+/.test(label)
  
  layer.id == 'orthography' && first('participant').label == 'Robert' && first('utterance').start.offset == 12.345
  
  graph.id == 'AdaAicheson-01.trs' & layer.id == 'orthography' & start.offset > 10.5
  
  previous.id == 'ew_0_456'
  
  NB all expressions must match by either id or layer.id.
  pageLength (Optional) - The maximum number of annotations to return, or absent to return all.
  
  pageNumber (Optional) - The zero-based page number to return, or absent to return the first page.
  
  Returns:
  
  A list of matching Annotations.
- /api/store/aggregateMatchingAnnotations
  
  Identifies a list of annotations that match a particular pattern, and aggregates their labels.
  This allows for counting, listing distinct labels, etc.
  Parameters:
  
  operation - The aggregation operation(s) - e.g.
  
  DISTINCT
  List the distinct labels.
  
  MAX
  Return the highest label.
  
  MIN
  Return the lowest label.
  
  COUNT
  Return the number of annotations.
  
  COUNT DISTINCT
  Return the number of distinct labels.
  
  More than one operation can be specified, by using a comma delimiter. e.g. "DISTINCT,COUNT" will return each distinct label, followed by its count (i.e. the array will have twice the number of elements as there are distinct words, even-indexed elements are the word labels, and odd-indexed elements are the counts).
  expression - An expression that determines which transcripts match.
  The expression language is currently not well defined, but expressions such as the following can be used:
  
  layer.id == 'orthography'
  
  graph.id == 'AdaAicheson-01.trs' && layer.id == 'orthography'
  
  NB all expressions must match by either id or layer.id.
  Returns:
  
  A list of results. This may have a single element (e.g. when operation == COUNT), or may be a (long) list of labels (e.g. when operation == DISTINCT. If there are multiple operations then the array will contain a multiple of the number of matching annotations. (e.g. if operation == DISTINCT,COUNT then the array will have twice the number of elements as there are distinct words, even-indexed elements are the word labels, and odd-indexed elements are the counts.)
- /api/store/countAnnotations
  
  Gets the number of annotations on the given layer of the given transcript.
  
  Parameters:
  
  id - The ID of the transcript.
  
  layerId - The ID of the layer.
  
  maxOrdinal - (Optional) The maximum ordinal for the counted annotations. e.g. a maxOrdinal of 1 will ensure that only the first annotation for each parent is counted. If maxOrdinal is null, then all annotations are counted, regardless of their ordinal.
  
  Returns:
  
  A (possibly empty) array of annotations.
- /api/store/getAnnotations
  
  Gets the annotations on the given layer of the given transcript.
  
  Parameters:
  
  id - The ID of the transcript.
  
  layerId - The ID of the layer.
  
  maxOrdinal - (Optional) The maximum ordinal for the returned annotations. e.g. a maxOrdinal of 1 will ensure that only the first annotation for each parent is returned. If maxOrdinal is null, then all annotations are counted, regardless of their ordinal.
  
  pageLength (Optional) - The maximum number of IDs to return, or absent to return all.
  
  pageNumber (Optional) - The zero-based page number to return, or absent to return the first page.
  
  Returns:
  
  A (possibly empty) array of annotations.
- /api/store/getAnchors
  
  Gets the given anchors in the given transcript.
  
  Parameters:
  
  id - The ID of the transcript.
  
  anchorIds - A list of anchor IDs, passed by specifying the anchorIds parameter multiple times, once for each anchor.
  
  Returns:
  
  A (possibly empty) array of anchors.
- /api/store/getTranscript
  
  Gets a transcript given its ID, containing only the given layers.
  
  Parameters:
  
  id - The given transcript ID.
  
  layerIds - The IDs of the layers to load, passed by specifying the layerIds multiple times, once for each layer, or absent if only transcript data is required.
  
  Returns:
  
  The identified transcript, encoded as JSON.
- /api/store/getFragment
  
  Gets a fragment of a transcript, given its ID and the ID of an annotation in it that defines the desired fragment, and containing only the given layers.
  
  Parameters:
  
  id - The ID of the transcript.
  
  annotationId - The ID of an annotation that defines the bounds of the fragment.
  
  layerIds - The IDs of the layers to load, passed by specifying the layerIds multiple times, once for each layer, or absent if only transcript data is required.
  
  Returns:
  
  The identified transcript fragment, encoded as JSON.
- /api/store/getFragment
  
  Gets a fragment of a transcript, given its ID and the start/end offsets that define the desired fragment, and containing only the given layers.
  
  Parameters:
  
  id - The ID of the transcript.
  
  start - The start offset of the fragment.
  
  end - The end offset of the fragment.
  
  layerIds - The IDs of the layers to load, passed by specifying the layerIds multiple times, once for each layer, or absent if only transcript data is required.
  
  Returns:
  
  The identified transcript fragment, encoded as JSON.
- /api/store/getMediaTracks
  
  List the predefined media tracks available for transcripts.
  
  Returns:
  
  An ordered list of media track definitions.
- /api/store/getAvailableMedia
  
  List the media available for the given transcript.
  
  Parameters:
  
  id - The transcript ID.
  
  Returns:
  
  List of media files available for the given transcript.
- /api/store/getMedia
  
  Gets a given media track for a given transcript.
  
  Parameters:
  
  id - The transcript ID.
  
  trackSuffix (Optional) - The track suffix of the media - see MediaTrackDefinition.suffix.
  
  mimeType - The MIME type of the media, which may include parameters for type conversion, e.g. "text/wav; samplerate=16000"
  
  startOffset (Optional) - The start offset of the media sample, or null for the start of the whole recording.
  
  endOffset (Optional) - The end offset of the media sample, or null for the end of the whole recording.
  
  Returns:
  
  A URL to the given media for the given transcript, or null if the given media doesn't exist.
- /api/store/countMatchingAnnotations
  
  Counts the number of annotations that match a particular pattern.
  Parameters:
  expression - An expression that determines which participants match.
  The expression language is currently not well defined, but expressions such as the following can be used:
  
  id = 'ew_0_456'
  
  !/th[aeiou].+/.test(label)
  
  layer.id == 'orthography' && first('participant').label == 'Robert' && first('utterance').start.offset == 12.345
  
  graph.id == 'AdaAicheson-01.trs' & layer.id == 'orthography' & start.offset > 10.5
  
  previous.id == 'ew_0_456'
  
  NB all expressions must match by either id or layer.id.
  Returns:
  
  The number of matching annotations.
- /api/store/getMatchingAnnotations
  
  Gets a list of annotations that match a particular pattern.
  Parameters:
  expression - An expression that determines which transcripts match.
  The expression language is currently not well defined, but expressions such as the following can be used:
  
  id = 'ew_0_456'
  
  !/th[aeiou].+/.test(label)
  
  layer.id == 'orthography' && first('participant').label == 'Robert' && first('utterance').start.offset == 12.345
  
  graph.id == 'AdaAicheson-01.trs' & layer.id == 'orthography' & start.offset > 10.5
  
  previous.id == 'ew_0_456'
  
  NB all expressions must match by either id or layer.id.
  pageLength - The maximum number of annotations to return, or null to return all.
  
  pageNumber - The zero-based page number to return, or null to return the first page.
  
  Returns:
  
  A list of matching Annotations.
- /api/store/getEpisodeDocuments
  
  Get a list of documents associated with the episode of the given transcript.
  
  Parameters:
  
  id - The transcript ID.
  
  Returns:
  
  List of URLs to documents.
- /api/store/getSerializerDescriptors
  
  Lists the descriptors of all registered serializers.
  Serializers are modules that export annotation structures as a specific file format, e.g. Praat TextGrid, plain text, etc., so the mimeType of descriptors reflects what mimeTypes can be specified for exporting annotation data.
  
  Returns:
  
  A list of the descriptors of all registered serializers.
- /api/store/getDeserializerDescriptors
  
  Lists the descriptors of all registered deserializers.
  Deserializers are modules that import annotation structures from a specific file format, e.g. Praat TextGrid, plain text, etc.
  
  Returns:
  
  A list of the descriptors of all registered deserializers.
- /api/store/getAnnotatorDescriptors
  
  Lists descriptors of all annotators that are installed.
  Annotators are modules that perform automated annations of existing transcripts.
  
  Returns:
  
  A list of the descriptors of all registered annotators.
- /api/store/getAnnotatorDescriptors
  
  Gets a descriptor of the annotator with the given ID.
  Annotators are modules that perform automated annations of existing transcripts.
  
  Parameters:
  
  annotatorId - The ID of the annotator.
  
  Returns:
  
  A list of the descriptors of all registered annotators.
- /api/admin/store/getAnnotatorTasks
  
  Supplies a list of automation tasks for the identified annotator.
  
  Parameters:
  
  annotatorId
  The ID of the annotator that performs the tasks.
  
  The response contains a model which represents a map of taskIds to descriptions.
- /api/admin/store/getAnnotatorTaskParameters
  
  Supplies the given task's parameter string.
  
  Parameters:
  
  taskId
  
  The ID of the task.
- /api/store/getTranscriberDescriptors
  
  Lists descriptors of all transcribers that are installed.
  Transcribers are modules that perform perform automated transcription of recordings that have not alreadye been transcribed.
  
  Returns:
  
  A list of the descriptors of all registered transcribers.
Author:

Robert Fromont robert@fromont.net.nz

Field Summary
- Fields inherited from class nzilbb.labbcat.server.api.APIRequestHandler
  SC_BAD_REQUEST, SC_CONFLICT, SC_FORBIDDEN, SC_INTERNAL_SERVER_ERROR, SC_METHOD_NOT_ALLOWED, SC_NOT_FOUND, SC_OK, SC_UNPROCESSABLE_CONTENT, SC_UNSUPPORTED_MEDIA_TYPE

Constructor Summary

Constructors
Constructor Description

Store()
Default constructor.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method	Description
`javax.json.JsonObject`	`get(String url, String method, String pathInfo, String queryString, RequestParameters parameters, InputStream requestBody, Consumer<Integer> httpStatus, Consumer<String> redirectUrl)`	GET handler lists all rows.

Methods inherited from class nzilbb.labbcat.server.api.APIRequestHandler
GetSystemAttribute, init, writeResponse

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail
- Store
```
public Store()
```
  Default constructor.

Method Detail

get

public javax.json.JsonObject get(String url,
                                 String method,
                                 String pathInfo,
                                 String queryString,
                                 RequestParameters parameters,
                                 InputStream requestBody,
                                 Consumer<Integer> httpStatus,
                                 Consumer<String> redirectUrl)

GET handler lists all rows.

The return is JSON encoded, unless the "Accept" request header, or the "Accept" request parameter, is "text/csv", in which case CSV is returned.

Parameters:: url - The URI of the request.; method - The HTTP request method, e.g. "GET".; pathInfo - The URL path.; queryString - The URL's query string.; parameters - Request parameter map.; requestBody - For access to the request body.; httpStatus - Receives the response status code, in case or error.; redirectUrl - Receives a URL for the request to be redirected to.
Returns:: JSON-encoded object representing the response

Class Store

/api/store/getId

/api/store/getLayerIds

/api/store/getLayers

/api/store/getSchema

/api/store/getLayer

/api/store/getCorpusIds

/api/store/getParticipantIds

/api/store/getParticipant

/api/store/countMatchingParticipantIds

/api/store/getMatchingParticipantIds

/api/store/getTranscriptIds

/api/store/getTranscriptIdsInCorpus

/api/store/getTranscriptIdsWithParticipant

/api/store/countMatchingTranscriptIds

/api/store/getMatchingTranscriptIds

/api/store/countMatchingAnnotations

/api/store/getMatchingAnnotations

/api/store/aggregateMatchingAnnotations

/api/store/countAnnotations

/api/store/getAnnotations

/api/store/getAnchors

/api/store/getTranscript

/api/store/getFragment

/api/store/getFragment

/api/store/getMediaTracks

/api/store/getAvailableMedia

/api/store/getMedia

/api/store/countMatchingAnnotations

/api/store/getMatchingAnnotations

/api/store/getEpisodeDocuments

/api/store/getSerializerDescriptors

/api/store/getDeserializerDescriptors

/api/store/getAnnotatorDescriptors

/api/store/getAnnotatorDescriptors

/api/admin/store/getAnnotatorTasks

/api/admin/store/getAnnotatorTaskParameters

/api/store/getTranscriberDescriptors

Field Summary

Fields inherited from class nzilbb.labbcat.server.api.APIRequestHandler

Constructor Summary

Method Summary

Methods inherited from class nzilbb.labbcat.server.api.APIRequestHandler

Methods inherited from class java.lang.Object

Constructor Detail

Store

Method Detail

get