Smntx REST API

The Smntx REST service is composed of four resources (user, instance, markup, search) that group operations based on user interaction. The API is JSON based, in most cases it accepts either a JSON object, query parameters or Form encoded parameters. In general results are returned as JSON objects.

Note: This API is under active development and may not reflect the current state.

REST Resource Summary

Resource Type	URL Mapping	Type Returned	REST Operation
User	/users/{username}	JSON	GET, PUT, DELETE
User	/users/{username}/groups/	JSON	GET, POST (All groups)
User	/users/{username}groups/{gpname}	JSON	GET, PUT, DELETE
Analysis	/analysis/{NLPTool}	JSON	POST (start analysis)
Analysis	/analysis/{analysisId}	JSON	GET, PUT, DELETE
Analysis	/analysis/{analysisId}/files	JSON	GET
Analysis	/analysis/{analysisId}/files/{fname}	JSON	GET
Markup	/analysis/{analysisId}	HTML	GET
Markup	/analysis/{analysisId}?{phraseid}	HTML	GET
Search	/search?{query}	JSON	GET, POST
Search	/search/saved/{searchid}	JSON	GET, POST, PUT, DELETE

Detailed REST Interface

User Resource (ctsa/rest/user/)

The user resource exposes an interface to store and retrieve information about individual users using the CTSA/MetaMap service. I imagine this service could be used for multiple NLP applications (metamap, medlee,...). We probably want this to interact with UMLS or globus.org user information and much of this code would then be redundant. However in its place we will need to validate user credentials and we would still probably need to record a mapping.

Create User [private] (ctsa/rest/user) POST

Checks user uniqueness, creates a personal directory for data storage, stores general user info. We will probably extend to check credentials – OpenID/globus.org/UMLS account. This will be only privately exposed as we wouldn’t want consumers creating user accounts.

• Parameters:
  • Name (or UserAccount)
• Returns:
  • UserAccount (name, id, working directory, patientgroups[], instances[])

Get User [private](ctsa/rest/user) GET

Given a user name retrieve the complete user information. This probably will just be used for testing, there is stuff in the user resource you probably don’t want to share with consumers.

• Parameters:
  • username
• Returns:
  • UserAccount: name, id, working directory, patientgroups[], instances[]

Delete User [private] (ctsa/rest/user) DELETE

Given a user name delete the complete user information and all associated analyses, patient groups and searches.

• Parameters:
  • userid
• Returns:
  • String (boolean)

Get Instances (ctsa/rest/user/instances) GET

Returns all instances associated with this user

• Parameters:
  • username
• Returns:
  • Instance[]: (id, name, type, path, input terms, input files, file path, interactive, result, date, status, args, user account id, markup id, patient group id)

Create Patient Group (ctsa/rest/user/patientgroups) POST

Create a new patient group for a given user. Supports both form encoded parameters and query parameters.

• Parameters:
  • username, patient group name
• Returns:
  • PatientGroup: id, name, user account, instances[]

Get Patient Groups (ctsa/rest/patientgroups) GET

Returns all patient groups associated with this user

• Parameters:
  • username
• Returns:
  • Patient Groups[] § id, name, user account, instances[]

Get Files (ctsa/rest/user/files) GET

Returns a list of files uploaded by this user.

• Parameters:
  • username
• Returns:
  • File Bean []: (file name, file size, last modified)

Upload File (ctsa/rest/user/files) POST

Uploads one or more files using apache commons file upload servlet. The good thing about this package is we can support multiple file upload in a single request and it is apparently quite efficient.

• Parameters:
  • Username, HTTPServletRequest (file data)
• Returns:
  • void

Download File (ctsa/rest/user/files) GET

Returns the file using the appropriate MIME type so it can be shown in a browser window

• Parameters:
  • Username, filename
• Returns:
  • HTTP Response – file using appropriate MIME Type

InstanceResource (ctsa/rest/metamap/)

The instance resource represents an individual MetaMap analysis instance. The API exposes methods to create, start, and monitor running analysis and also retrieve results.

Create Analysis (ctsa/rest/metamap) POST

Starts a new MetaMap analysis by invoking the MetaMap API. This method can be invoked with a JSON Instance object , form encoded parameters (/form)or query params (/query). The REST service checks the user is registered, creates an instance directory, adds the instance to database. Executes MetaMap in interactive or batch mode using a string of terms or an input file. In batch mode the request is sent to a thread pool queue to run the instance asynchronously, in interactive mode the service is called synchronously and blocks until results are generated. In batch mode a reference to the running instance is returned, in interactive mode results are included in the returned instance.

• Parameters:
  • Username, Instance( Instance name, patient group id, arguments[], interactive/batch mode, input terms, input files)

OR form/query params

• Parameters:
  • Username, instance name, input terms, input files[], patient group id, arguments [], interactive/batch mode
• Returns:
  • Instance (Same parameters along with: id, status, result, markupid)

Update Analysis (ctsa/rest/ metamap) PUT

Re-execute the analysis using updated arguments.

• Parameters:
  • Instance id, args []
• Returns:
  • Instance

Get Analysis (ctsa/rest/metamap) GET

Get an instance by instance id. Used for data provenance and also retrieving plain results (in batch mode)

• Parameters:
  • Instance id
• Returns:
  • Instance

Get Patient Group(ctsa/rest/metamap/patientgroup) GET

Get the patient group for this instance. Separate method as the analysis doesn’t contain patient group due to circular referencing.

• Parameters:
  • Instance id
• Returns:
  • Patient group

Get Files (ctsa/rest/ metamap /files) GET

Returns a list of files belonging to this particular instance, for example output files.

• Parameters:
  • instanceid
• Returns:
  • File Bean []: (file name, file size, last modified)

Download File (ctsa/rest/ metamap /files) GET

Returns the file using the appropriate MIME type so it can be shown in a browser window

• Parameters:
  • Instance id, filename
• Returns:
  • HTTP Response – file using appropriate MIME Type

MarkupResource (ctsa/rest/markup/):

The markup resource exposes access to HTML markup of the input terms, it also selects sections of the original text based on phrases that are returned for context

Get MarkupText(ctsa/rest/ markup/text) GET

Get an HTML version of the original input terms. The input terms are marked up with uniquely identified <span> tags around matched phrases. Each span tag can then be highlighted in the rendered HTML using a client side filter. Each phrase/span is identified and mapped to a markup mapping object that maps candidates and mappings to the relevant phrase.

• Parameters:
  • Markup id
• Returns:
  • HTML input terms

Get Markup Object (ctsa/rest/markup/object) GET

Get the markup map that contains all candidates and mappings generated as a result of MetaMap parsing. Each candidate/mapping is mapped to a single phrase ID in the related HTML markup text.

• Parameters:
  • Markup id
• Returns:
  • Markup Object: (Phrase id, phrase, candidates[], mappings[])

Get Markup Utterance (ctsa/rest/markup/utterance) GET

Get the markup around a particular phrase in the input text. This selects `length’ characters around the given phrase and strips all other markup from the returned utterance.

• Parameters:
  • instanceid, phraseid, length
• Returns:
  • HTML Utterance

SearchResource (ctsa/rest/search/)

The search resource exposes a search interface to users allowing them to run standard and faceted search using a subset of the Solr (or Lucene) query language.

Search (ctsa/rest/search) GET/POST

Searches over the users’ analysis documents given constraints on the analysis instance or patient group. The same functionality is exposed through POST (form params) and GET (query params). The query field is a full text search over any field. The other parameters are used to filter the query range on the user defined text field. The API also allows specification of maximum number of results and start positions for paging. The user can also specify if the results should include faceted search.

• Parameters:
  • Required: username, faceted search
  • Optional: rows, start, query, instance id, patient group name, instance name, semantic type, search phrase, preferred name, concept name, mappings, source, score, negation
• Returns:
  • Solr search result: (Query type, facets, facet_range, matching documents)

Update Search (ctsa/rest/search) PUT

Update a single row in the Solr text repository. Can be invoked through form params or query params (/query). Allows users to improve existing mappings.

• Parameters:
  • Required: rowid,
  • Optional: score, semantic type, preferred name, negation id, negation.
• Returns:
  • boolean

Delete Search (ctsa/rest/search) PUT

Update a single row in the Solr text repository.

• Parameters:
  • Required: rowid,
• Returns:
  • boolean

Advanced; Search (ctsa/rest/advanced) GET

Allow a user constructed query string using Solr/Lucene query language.

• Parameters:
  • Required: username, rows, start, query
• Returns:
  • Solr search result: (Query type, facets, facet_range, matching documents)

Save Search (ctsa/rest/saved) POST

Save a particular search along with a name and the number of results returned last time the query was executed. Can be invoked through form params or query params (/query).

• Parameters:
  • Required: username, searchname, searchterms, searchnumresults
• Returns:
  • Search object (id, name, terms, numresults, search date)

Get Saved Search (ctsa/rest/saved) GET

Retrieve all previously saved searches for a particular user.

• Parameters:
  • Required: username
• Returns:
  • Search object []: (id, name, terms, numresults, search date)

Delete Saved Search (ctsa/rest/saved) DELETE

Delete a previously saved search.

• Parameters:
  • Required: username, search id
• Returns:
  • Solr search result:(Query type, facets, facet_range, matching documents)