User GuidesSnapGene Server Guide ManualSnapGene Server Request API

SnapGene Server Request API

A list of currently supported commands, their parameters and a description of the command.

Common Parameters

Several commands use a common set of names to specify parameters:

See Enzyme Set Names.

See Reading Frame Names.

General Commands

Request Server Status

Requests status information for the server. Can be used to "ping" the server and make sure it is still operational. This request doesn't actually change any the server status information (lastRequest, requestCount).

Input Parameters
request “status"
Output Parameters
response
“status"
serverVersion Version number of the serverver 
requestCount 

Number of requests to the server (this request does not count)

lastRequest Time of the last request (this request does not count)
uptime Time the server has been running
license State of the current license (if it is found, valid, expiration, etc.)
licenseExpiration Date of the license expiration (YY-MM-DD)
Errors
0 Success

Report File Information

Input Parameters
request “reportFileInfo"
inputFile full path to input .dna file
Output Parameters
response
“reportFileInfo"
code error code
sequenceLength length of the sequence in base pairs
sequenceTopology either “circular” or “linear"
serverIndex index of server daemon that ran the report
Error Codes
0 Success
1 Unable to open input .dna file or it isn’t a DNA file

File Conversion

Import DNA File

Converts a file from a different DNA format to snapgene native .dna.

Input Parameters
request “importDNAFile"
inputFile full path to file to import
outputFile Full path to .dna file to write to disk
enzymeSet Enzyme set to save to this file (see list of possible names below)
minORFLen Minimum detection length for ORFs to save to this file. Default is 75.
readingFrames Reading frame option to save with this file (see list of possible names below). Default is ORFS
Output Parameters
response
“importDNAFile"
code Return code for the request
Error Codes
0 Success
1 Could not open input file
2 File tupe unsupported
4 Could not create output file
5 File stamping failure
6 Encoding failed
7 MICA Indexing failed
8 Recognition sequence indexing failed

Export DNA File

Converts a file from snapgene native .dna to another file format. The outputFile must contain the extension .gb[1] or .fasta to convert to that particular format. Otherwise the output format is ambiguous and will the request will fail.

Input Parameters
request “exportDNAFile"
inputFile full path to file to read
outputFile Full path of file to write to disk
exportFilter Type of filter to export. Currently supported export filters are listed below.
Output Parameters
response
“exportDNAFile"
code Return code for the request
Error Codes
0 Success
1 Unable to open input file or the file is not a .dna file
2 Export filter unsupported
3 Internal exporting code failed

Feature Commands

Detect Features

Detects feature on a .dna file. Will only detect new features present in the input feature database.

To detect from multiple databases, call this command repeatedly. Input and output parameters can be the same to modify the file in place.

For each new feature added, an optional note is appended to the feature's /note field (as specified in the genbank file format. This can also be viewed in Snapgene Desktop in the /note field at the bottom of the edit features dialog box.

Input Parameters
request “detectFeatures"
inputFile Full path to .dna file to read
outputFile Full path of .dna file to write to disk
featureDatabase Full path to feature database file. This should use the .dna file format but often uses the extension .ftrs (either will work.
Output Parameters
response
“detectFeatures"
code Return code for the request
Error Codes
0 Success
1 Unable to open input file
2 Unable to create output file
3 Feature database file does not exist

Report Features

Returns the list of all features in the inputFile.

Input Parameters
request “reportFeatures"
inputFile Full path to .dna file to read
Output Parameters
response
“reportFeatures"
features Array of features
code Return code for the request
Error Codes
0 Success
1 Unable to open input file

The feature object is of the following format:

Feature Objects
name name of the feature
type type of the feature (there are many--I don't have them all listed here)
rangebegin beginning base pair of the entire feature
rangeEnd ending base pair of the entire feature
direction can be one of the following: nondirectional, forward-directional, reverse-directional, bidirectional
segments array of segments, introns are not included.
attributes object with many key/value pairs, they are not all listed here. Values are string arrays.

The segment object is of the following format:

Segment Objects
name name of the segment
rangeBegin beginning base pair of the segment
rangeEnd ending base pair of the segment
color color of the segment in #AAAAAAAA format
type can be one of the following: standard, gap, run-on-translation

Generate SVG Map

Input Parameters
request
“generateSVGMap”
inputFile
full path to .dna file to generate map from
linear
true for linear map, false for circular map
showEnzymes
True to show enzymes on the map
showPrimers
True to show primers on the map
showFeatures
True to show features on the map
showORFs
True to display ORFs on the map
designSize
set the requested size of the map in width x height.  The actual size might be different because the map generation code performs extra logic to ensure the text graphical elements are all visible
outputSvgDom
file to text fragment of the svg objects and tooltip DOM objects
outputSvgJSStatic
file to text fragment of the javascript code required for hover/selection (static part) the static part can be shared for all maps for the same version of snapgene server.

NOTE: this parameter is deprecated --- there is no need to generate JS files using generateSVGMap. Instead use the JS file in /opt/gslbiotech/snapgene-server/examples/js/map-seq-interactivity.js
outputSvgJSDynamic
file to text fragment of the javascript code required for hover/selection (dynamic part).

NOTE: this parameter is deprecated
outputSvgCss
file to text fragment of the css code required for proper rendering of the SVG DOM.

NOTE: this parameter is deprecated
optimize
Removes extra SVG attributes that are not necessary for correctly rendering the SVG.
dataModel
User defined attribute used to identify a particular map or sequence view.  Useful when supporting multiple maps or sequences on the same page
dataId
User defined attribute used to identify a particular map or sequence view.  Useful when supporting multiple maps or sequences on the same page.
title
Defines the title to use for the map.  If the title is not defined or set to an empty string, then the default title (the filename without the extenion) is used.  To clear the title completely from display, set the value to one space, e.g. “ “.
subtitle
Defines the subtitle to use for the map.  If the subtitle is not defined or set to an empty string, then the default title (the number of base pairs) is used.  To clear the title completely from display, set the value to one space, e.g. “ “.
addMouseEvents
Adds mouse handlers in the hittest region of the DOM.  Default is true.
enzymeSet
Override enzyme set to use saved with the .dna file
minORFLen
Override the minimum ORF length saved with the .dna file
readingFrame
Override the reading frame saved with the .dna file
Output Parameters
response "generateSVGMap"
code Return code for the request
Errors
0
Success
1
Update to open input for or it isn't a DNA file
2
DNA file can be opened, requires updating, but couldn't be updated
4
Unable to write SVG file
5
Unable to write JS file
6
Unable to write CSS file
100
Internal Error

Generates a web based map in several text file fragments.

The DOM object returned from outputSvgDOM will contain attributes with data-sequence-length and data-topology.

NOTE: This method used to be called generateMapParts.

Generate PNG Map

Generates a similar map compared to generateSVGMap except the output is PNG instead of Dom, JS and css files.

Input Parameters

request
"generatePNGMap"
inputFile
full path to .dna file to generate map from
linear
true for linear map, false for circular map
showEnzymes
true to display enzymes
showFeatures
true to display features
showPrimers
true to display primers
showORFs
true to display ORFs
designSize
set the requested size of the map in width x height. The actual size might be different because the map generation code performs extra logic to ensure the text graphical elements are all visible
outputPng
Output PNG file
enzymeSet
Override enzyme set to use saved with the .dna file
minORFLen
Override the minimum ORF length saved with the .dna file
readingFrame
Override the reading frame saved with the .dna file
Output Parameters
response “generatePNGMap"
code error code for the request
Error Codes
0 Value 2
1 Update to open input for or it isn't a DNA file
2 DNA file can be opened, requires updating, but couldn't be updated
100 Internal error

Generate SVG Sequence

Input Parameters
request
generateSVGSequence
inputFile
full path to .dna file to generate a sequence from
showEnzymes
true to display enzymes
showFeatures
true to display features
showPrimers
true to display primers
showTranslation
true to display translations (this is currently unsupported)
outputSvgDom
file to text fragment of the svg objects
outputSvgJSStatic
file to text fragment of the javascript code required for hover/selection (static part) the static part can be shared for all maps for the same version of snapgene server.
outputSvgJSDynamic
file to text fragment of the javascript code required for hover/selection (dynamic part)
outputSvgCss
file to text fragment of the css code required for proper rendering of the SVG DOM
optimize
Removes extra SVG attributes that are not necessary for correctly rendering the SVG.

User defined attribute used to identify a particular map or sequence view. Useful when supporting multiple maps or sequences on the same page.

User Defined
dataID User defined attribute used to identify a particular map or sequence view.
addMouseEvents
Adds mouse handlers in the hittest region of the DOM. Default is true.
enzymeSet Override enzyme set to use saved with the .dna file
minORFLen Override the minimum ORF length saved with the .dna file
readingFrame Override the reading frame saved with the .dna file
Output Parameters
response “generateSVGSequence"
code Error code for 
Error Codes
0 Success.
1 Update to open input for or it isn't a DNA file.
2 DNA file can be opened, requires updating, but couldn't be updated.
4 Unable to write SVG file.
5 Unable to write JS file.
6 Unable to write CSS file.
100 Internal Error.

Generates a web-based sequence in several fragments.

Import Primers from List

Input Parameters:
request
importPrimersFromList
inputFile
full path to input .dna file
inputPrimerFile
full path to json file with primers to import
outputDnaFile
full path to output .dna file with imported primers
requirePerfectMatch
Integer value. 0 means no perfect match required. -1 means a perfect match is required for the entire primer. A value between 12-25 means a perfect match is required for that many bases of the primer.
requireUniqueBindingSite
true/false. Require a unique binding site for the primer to be imported.
Output Parameters
response “importPrimersFromlist"
code Error
Error Codes:
0 Success.
1 Unable to open input dna file or it isn’t a DNA file.
2 DNA file can be opened, requires updating, but couldn’t be updated.
3 Unable to open primer file.
4 Unable to write output DNA file.
100 Internal error.

Reads a list of primers in a json document and inserts them into a dna file. A new dna file is written.

The primer json document is of the following format:

array of objects of members. Members are:

[Primer Item 1, Primer Item 2, ...]

Each primer Item is:

{
"Name":"<primer name>", 
"Sequence":"<primer sequence>",
 "Notes":"<primer notes>"
}

Report Primers

Input Parameters
request “reportPrimers"
inputDNAFile full path to input.
Output Parameters
response “reportPrimers"
code error code
primers json array of primers (see schema below)
Error Codes:
0 Success
1 Unable to open input dna file or it isn’t a DNA file.
2 DNA file can be opened, requires updating, but couldn’t be updated.
100 Internal error.

Opens a .dna file and outputs a report in JSON for all primers saved to the .dna file.

JSON Schema for primers:

  • color-user friendly name of color for primer
  • length-length of sequence (this is always the same as property character length
  • molecularWeight-formated string with weight of the primer
  • name-name of the primer
  • notes-notes for the primer
  • percentGC-formated string with the percentage GC for the sequence
  • sequence-actual sequence string of the primer
  • sites-JSON array of binding sites
    • bindingSiteStart: start of the binding site in BP
    • bindingSiteEnd: ending of the binding site in BP
    • meltingTemperature: degrees centigrade for melting
    • strand: specified which side of the sequence the primer is attached to (“Top” or“Bottom”)

Example output with four primers. One of the primers has two binding sites:

{
"code": 0,
"primers": [
{
     "color": "Black",
     "length": 39,
     "molecularWeight": "12,107.9 Da",
     "name": "A206K.REV",
     "notes": "<html><body>For introducing the monomerizing A206K mutation</body></html>",
     "percentGC": "56% GC",
     "sequence": "GTTGGGGTCTTTGCTCAGCTTGGACTGGGTGCTCAGGTA",
     "sites": [
}, {
{
} ]
"bindingSiteEnd": 2593,
"bindingSiteStart": 2555,
"meltingTemperature": 71,
"strand": "Bottom"
"color": "Black",
"length": 39,
"molecularWeight": "11,868.7 Da",
"name": "A206K.FOR",
"notes": "<html><body>For introducing the monomerizing A206K mutation</body></html>",
"percentGC": "56% GC",
"sequence": "TACCTGAGCACCCAGTCCAAGCTGAGCAAAGACCCCAAC",
"sites": [
{
}, {
} ]
"bindingSiteEnd": 2593,
"bindingSiteStart": 2555,
"meltingTemperature": 71,
"strand": "Top"
"bindingSiteEnd": 2593,
"bindingSiteStart": 2555,
"meltingTemperature": 71,
"strand": "Top"
},
"response": "reportPrimers"
}

Report Enzymes

Report ORFs

Input Parameters
request “reportEnzymes"
inputFile full path to input .dna file.
enzymeSet enzyme set to use (see list of possible names below). Otherwise enzyme set saved with file is used.
Output Parameters
response “reportEnzymes"
code Error code.
setName Name of the enzyme set.
count Number of enzymes in library.
enzymes json array of enzymes (see schema below).
Error Codes
0 Success.
1 Unable to open input dna file or it isn’t a DNA file.
For each JSON object in the enzymes JSON array:

id: Unique identifier for the enzyme. This should match with the map or sequence.
name: Name of the enzyme.
Hits: JSON array of hit objects (locations the enzyme cuts the sequence.
Each hit object contains the following:

topCutPosition:
Top location of the enzyme cut (this is the typical value displayed).
bottomCutPosition:
If the cut is not blunt, then the bottom base position will be offset from the top.
methylationSensitive:
true or false.
blocked: true or false.

Report ORFs

Input Parameters
request “reportORFs"
inputFile full path to input .dna fi
Ouput Parameters
response “reportORFs"
code error code
ORFs jsonArray of ORF objects.
Error Codes:
0 Success
1 Unable to open input dna file or it isn’t a DNA file.
Response fields for each ORF:
fullRangeBegin:
First codon of ORF.
fullRangeEnd: Last codon of ORF.
hitsStopCodon:
True if fullRangeEnd is the last codon. It is possible the plasmid ends before a stop codon is encountered.
lacksStartCodon:
In some configurations of ORF detection of a start codon is not required, if an ORF is detected without a start codon within the plasmid (i.e. the beginning of a linear map), this flag would be true.