Skip to main content

%UIMA.REST.v1

This capability is being deprecated and will be removed in a future release of InterSystems IRIS. Please reach out to your account team if you need an alternative solution.

This class offers endpoints for accessing UIMA functionalities over REST.

The API is fully documented using the OpenAPI SpecificationOpens in a new tab (also known as SwaggerOpens in a new tab). The description in YAML is available from the "/swagger" endpoint and can be loaded directly into swagger-uiOpens in a new tab for convenient GUI capabilities on top of this API.

swagger: '2.0'
info:
  version: "1.0.0"
  title: InterSystems UIMA REST APIs
  description: |
    This is the [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification) 
    of the UIMA REST APIs, giving you RESTful access to Annotation Store contents in your system.
    Use [swagger-ui](https://github.com/swagger-api/swagger-ui/blob/master/README.md)
    or a similar tool to conveniently browse and test these APIs.
    For more information on UIMA, visit [intersystems.com](http://www.intersystems.com) or
    [Apache UIMA](http://uima.apache.org).
  contact:
    name: InterSystems
    url: http://wrc.intersystems.com
    email: support@intersystems.com
consumes:
  - application/json
produces:
  - application/json
parameters:
  ASNameParam:
    name: annotationStore
    type: string
    in: path
    description: the (package) name of the annotation store to query
    required: true
  DocIDParam:
    name: docID
    type: string
    in: path
    description: the ID of the document to query for
    required: true
definitions:
  AnnotationStoreInfo:
    type: object
    description: metadata and statistics about a given Annotation Store
    required: ["name","annotationTables"]
    properties:
      name:
        description: annotation store name
        type: string
      identifier:
        description: identifier of the object managing this annotation store
        type: string
      annotationTables:
        description: list of annotation tables for this store
        type: array
        items:
          type: object
          required: ["name", "columns"]
          properties:
            name:
              description: annotation table name
              type: string
            topLevel:
              description: whether or not this table stores TOP-level annotations
              type: boolean
              format: integer
            columns:
              type: array
              items:
                type: object
                required: ["name","type"]
                properties:
                  name:
                    type: string
                  type:
                    type: string
                  paths:
                    type: array
                    items:
                      type: object
            filters:
              type: array
              items:
                type: object
            indices:
              type: array
              items:
                type: object
            stats:
              type: object
              title: runtime statistics
              description: runtime statistics for this annotation table
              properties:
                rowCount:
                  description: number of records in this table
                  type: integer
                types:
                  description: list of annotation types in this table
                  type: array
                  items:
                    type: string
  ASRequestObject:
    type: object
    description: request object specifying which annotations to retrieve
    properties:
      maxRows:
        type: integer
        description: maximum number of annotations to retrieve
        default: 500
      columns:
        type: array
        description: list of columns to retrieve, use "*" to retrieve all
        default: ["*"]
        items:
          type: string
      tables:
        type: array
        description: list of tables to retrieve annotations from. leave empty for all 
        default: []
        items:
          type: string
      docIDs:
        type: array
        description: list of documents (idenfied by ID) for which to retrieve annotations
        default: [ 123 ]
        items:
          type: string
      types:
        type: array
        description: list of types of annotations to retrieve. leave empty for all
        default: []
        items:
          type: string
  CASRaw:
    type: object
    description: CAS representation formatted as JsonCasSerializer output
    required: ["_context","_views","_referenced_fss"]
    properties:
      _context:
        type: object
        description: general information on the CAS being serialized
        required: ["_types"]
        properties:
          _types:
            type: object
            description: map of detailed type information, indexed by shortname
            properties:
              ShortName:
                type: object
                description: type information for type with shortname 'SomeType'
                required: ["_id"]
                properties:
                  _id: 
                    type: string
                    description: full type name
                  _feature_types:
                    type: object
                    description: map of nondefault feature types
                    properties:
                      someFeature:
                        type: string
                        description: type of feature
                        enum: ["_ref", "_array", "_binary"]
                  _subtypes:
                    type: array
                    description: list of subtypes (identified by their shortname)
                    items:
                      type: string
      _views:
        type: object
        description: map of the views for this CAS, indexed by view name
        properties:
          _InitialView:
            type: object
            description: map of all types in the view, indexed by type shortname
            properties:
              someType:
                description: array of all annotations in the view of this type
                type: array
                items: 
                  type: object
      _referenced_fss:
        type: object
        description: map of the referenced feature structures from the _views object, indexed by reference
        properties:
          someReference:
            type: object
            description: a feature structure
            required: ["_type"]
            properties:
              _type:
                type: string
                description: the shortname for this FS' type
  Markup:
    type: object
    description: specification for how to mark up text contents
    properties:
      method:
        type: string
        description: how actual markup is specified (such as CSS classes)
        default: "CSS"
        enum: ["CSS"]
      feature:
        type: string
        description: annotation property by which to define distinct styles
        default: "type"
      styleMap:
        type: object
        description: if supplied, this will take precedence over the top-level per-type generated ones
        example: { "com.intersystems.*": "my-css-class", "org.uima.alchemyapi.*": "my-other-css-class" }
        default: {}
  FullDocument:
    type: object
    description: representation of the entire document
    required: ["sofas", "CAS"]
    properties:
      sofas:
        type: array
        items:
          type: object
          description: SofA
          required: ["_id", "sofaID", "mimeType", "sofaString"]
          properties:
            _id:
              type: integer
              description: Internal ID of this SofA in the Annotation Store's Sofa table
            _ref:
              type: integer
              description: Reference of this SofA in the CAS
            sofaID:
              type: string
              description: SofA name in the CAS
              example: "_InitialView"
            sofaString:
              type: string
              description: sofaText
            mimeType:
              type: string
              example: "text"
      CAS:
        $ref: '#/definitions/CASRaw'

Method Inventory

Methods

classmethod GetAnnotationStoreInfo(namespace As %String, pAnnotationStoreName As %String) as %Status
      summary: |
        Retrieves basic information about an Annotation Store
      parameters:
        - $ref: '#/parameters/ASNameParam'
        - name: requestObject
          description: JSON object with a list of query-specific arguments
          in: body
          schema:
            type: object
            properties:
              noStats:
                description: whether or not to include annotation count and type lists in the result
                type: boolean
                default: 0
                format: integer
                
      responses:
        200:
          description: Successful response
          schema: 
            $ref: '#/definitions/AnnotationStoreInfo'
classmethod GetAnnotations(namespace As %String, pAnnotationStoreName As %String) as %Status
      summary: |
        Retrieves a list of annotations
      parameters:
        - $ref: '#/parameters/ASNameParam'
        - name: requestObject
          description: JSON object with a list of query-specific arguments
          in: body
          schema:
            $ref: '#/definitions/ASRequestObject'
                
      responses:
        200:
          description: Successful response
          schema: 
            $ref: '#/definitions/CASRaw'
classmethod GetDocument(namespace As %String, pAnnotationStoreName As %String, pDocID As %RawString) as %Status
      summary: |
        Retrieves all details for a given document
      parameters:
        - $ref: '#/parameters/ASNameParam'
        - $ref: '#/parameters/DocIDParam'
        - name: requestObject
          description: JSON object with a list of query-specific arguments
          in: body
          schema:
            type: object
            properties:
              annotations:
                $ref: '#/definitions/ASRequestObject'
              markup:
                $ref: '#/definitions/Markup'
                
      responses:
        200:
          description: Successful response
          schema: 
            $ref: '#/definitions/FullDocument'
classmethod Process(namespace As %String) as %Status
Accepted parameters: - data = "" - descriptors: array of descriptor specs - language - additionalClasspath: array of classpath entries - markup: object representing the required markup see GetSofa() Returns -
      summary: |
        Processes a given piece of text with a UIMA AE
      parameters:
        - name: requestObject
          description: JSON object with a list of query-specific arguments
          in: body
          schema:
            type: object
            required: ["data", "descriptors"]
            properties:
              data:
                type: string
                description: text to process
              descriptors:
                type: array
                description: array of AE descriptors to use for processing this string
                example: [ "C:\\Programs\\apache-uima\\examples\\descriptors\\tutorial\\ex1\\RoomNumberAnnotator.xml" ]
                items:
                  type: "string"
              language:
                type: string
                description: ISO language code to use
                example: "en"
              additionalClasspath:
                type: array
                description: additional libraries to add to the classpath in order to run these AEs
                example: [ "C:\\Programs\\apache-uima\\lib\\uima-examples.jar" ]
                items:
                  type: string
              markup:
                $ref: '#/definitions/Markup'
                
      responses:
        200:
          description: Successful response
          schema: 
            $ref: '#/definitions/FullDocument'

Inherited Members

Inherited Methods

FeedbackOpens in a new tab