dbBact restAPI

Server location

The production dbBact restAPI can be accessed at: http://api.dbbact.org

dbBact API commands

Following is the list of API endpoints (click on an endpoint for details):

/annotations/add

    Title: Add new annotation
    URL: /annotations/add
    Method: POST
    URL Params:
    Data Params: JSON
        {
            "expId" : int
                (expId from ExperimentsTable)
            "sequences" : list of str (ACGT)
                the sequences to add the annotation to
            "region" : str (optional)
                the name of the primner region where the sequence is from or None for 'na'
                (id from PrimersTable)
            "annotationType" : str
                annotation type (differential expression/contaminant/etc.)
                (description from AnnotationTypesTable)
            "method" : str (optional)
                The method used to detect this behavior (i.e. observation/ranksum/clustering/etc")
                (description from MethodTypesTable)
            "agentType" : str (optional)
                Name of the program which submitted this annotation (i.e. heatsequer)
                (description from AgentTypesTable)
            "description" : str (optional)
                Free text describing this annotation (i.e. "lower in green tomatoes comapred to red ones")
            "private" : bool (optional)
                default=False
                is this annotation private
                private from AnnotationsTable
            "annotationList" : list of
                {
                    "detail" : str
                        the type of detail (i.e. ALL/HIGH/LOW)
                        (description from AnnotationDetailsTypeTable)
                    "term" : str
                        the ontology term for this detail (i.e. feces/ibd/homo sapiens)
                        (description from OntologyTable)
                }
        }
    Success Response:
        Code : 201
        Content :
        {
            "annotationId" : int
            the id from AnnotationsTable for the new annotation.
        }
    Details:
        Validation:
            expId exists in ExperimentsTable
            sequences are all valid ACGT sequences
            region is a valid id from PrimersTable
        Action:
            iterate over sequences, if sequence does not exist, add it to SequencesTable (what to do about taxonomy? - keep it empty?)
            if currType does not exist, add it to AnnotationTypesTable
            if method does not exist, add it to MethodTypesTable
            if agentType does not exist, add it to AgentTypesTable
            iterate over all AnnotationList:
                if detail does not exist, add it to AnnotationsDetailsTypeTable
                if term does not exist, add it to OntologyNamesTable
            Create a new Annotation in AnnotationsTable
            Add all sequence/Annotation pairs to SequenceAnnotationTable
            Add all annotation details to AnnotationsTable (automatically adding userId and addedDate)
            Add all pairs to AnnotationListTable
    
/annotations/add_annotation_flag

    Title: add_annotation_flag
    Description : Flag an annotation as suspicious (i.e. wrong sequenes/region/terms/seems incorrect)
    URL: annotations/add_annotation_flag
    Method: POST
    URL Params:
    Data Params: JSON
        {
        annotationid: int
            The annotationID of the annotation to flag
        reason: str
            The reason to flag this annotation (as many details as possible)
        }
    Success Response:
        Code : 200
        Content :
        {
        }
    Details :
        Validation:
            Must be a registered user (cannot flag as annonimous)
            Must supply a reason
            Once an annotation is flagged, the flag status is "suggested". The flag will be reviewed by the dbbact team and then the status
            changed to "accepted" or "rejected"
    
/annotations/delete

    Title: delete
    Description : Delete annotation
    URL: annotations/delete
    Method: POST
    URL Params:
    Data Params: JSON
        {
            annotationid : int
                the annotationid to delete
        }
    Success Response:
        Code : 200
        Content :
        {
            annotationid : int
                the annotationid deleted
        }
    Details :
        Validation:
            If user is not logged in, cannot delete
            Can only delete annotations created by the user
    
/annotations/delete_annotation_flag

    Title: delete_annotation_flag
    Description : Delete an annotation flag (only if flag was created by the same user)
    URL: annotations/delete_annotation_flag
    Method: POST
    URL Params:
    Data Params: JSON
        {
        flagid: int
            The id of the annotation flag to delete
        }
    Success Response:
        Code : 200
        Content :
        {
            flags: list of dict {'flagid': int, status:str, userid: int}
        }
    Details :
        Validation:
        Can only delete if the user that created the flag is the user requesting delete
    
/annotations/delete_sequences_from_annotation

    Title: Delete sequences from annotation
    Description : Delete sequences from an existing annotation
    URL: annotations/delete_sequences_from_annotation
    Method: POST
    URL Params:
    Data Params: JSON
        {
            annotationid : int
                the annotationid to delete
            sequences : list of str ('ACGT')
                the sequences to delete from the annotation
        }
    Success Response:
        Code : 200
        Content :
        {
            annotationid : int
                the annotationid from which the sequences were deleted
        }
    Details :
        Validation:
            If user is not logged in, cannot delete non-annonymous
            Can only delete annotations created by the user
    
/annotations/get_all_annotations

    Title: get_all_annotations
    Description : Get list of all annotations in dbBact
    URL: annotations/get_all_annotations
    Method: GET
    URL Params:
    Data Params: JSON
        {
        }
    Success Response:
        Code : 200
        Content :
        {
            annotations : list of annotation
            See annotations/get_annotation() for details
        }
    Details :
        Validation:
            If an annotation is private, return it only if user is authenticated and created the curation. If user not authenticated, do not return it in the list
            If annotation is not private, return it (no need for authentication)
    
/annotations/get_annotation

    Title: get_annotation
    Description : Get the information about an annotation (based on annotationid)
    URL: annotations/get_annotation
    Method: GET
    URL Params:
    Data Params: Parameters or json
        {
            annotationid : int
                the annotationid to get the details for
        }
    Success Response:
        Code : 200
        Content :
        {
            "annotationid" : int
                the id of the annotation
            "userid" : int
                The user id
                (id from UsersTable)
            "username" : str
                name of the user who added this annotation
                (userName from UsersTable)
            "date" : str (DD-MM-YYYY HH:MM:SS)
                date when the annotation was added
                (addedDate from CurationsTable)
            "expid" : int
                the ID of the experiment from which this annotation originated
                (uniqueId from ExperimentsTable)
                (see Query Experiment)
            "annotationtype" : str
                annotation type (differential expression/contaminant/etc.)
                (can be 'highfreq'/'common'/'diffexp'/'isa'/'contamination'/'other')
                (description from CurationTypesTable)
            "method" : str
                The method used to detect this behavior (i.e. observation/ranksum/clustering/etc")
                (description from MethodTypesTable)
            "agent" : str
                Name of the program which submitted this annotation (i.e. heatsequer)
                (description from AgentTypesTable)
            "description" : str
                Free text describing this annotation (i.e. "lower in green tomatoes comapred to red ones")
            "private" : bool
                True if the curation is private, False if not
            "num_sequences" : int
                The number of sequences associated with this annotation
            "flags": list of dict {'flagid': int, status:str, userid: int}
                the flags raised for this annotation by other users (if not empty, maybe should suspect this annotation)
            'primerid': int
                id of the primer region of the annotation
            'primer': str
                name of the primer region of the annotation (i.e. 'v4')
            "details" : list of
                {
                    "detail" : str
                        the type of detail (i.e. ALL/HIGH/LOW)
                        (description from CurationDetailsTypeTable)
                    "term" : str
                        the ontology term for this detail (i.e. feces/ibd/homo sapiens)
                        (description from OntologyTable)
                }
        }
    Details :
        Validation:
            If an annotation is private, return it only if user is authenticated and created the curation. If user not authenticated, do not return it in the list
            If annotation is not private, return it (no need for authentication)
    
/annotations/get_annotation_flags

    Title: get_annotation_flags
    Description : Get flags associated with an annotation
    URL: annotations/get_annotation_flags
    Method: GET
    URL Params:
    Data Params: JSON
        {
        annotationid: int
            The annotationID of the annotation to get the flag
        }
    Success Response:
        Code : 200
        Content :
        {
            flags: list of dict {'flagid': int, status:str, userid: int}
        }
    Details :
        Validation:
    
/annotations/get_annotation_ontology_parents

    Title: get_annotation_ontology_parents
    Description : Get all the ontology terms (and their parents in the ontolgy DAG) for the annotation
    URL: annotations/get_annotation_ontology_parents
    Method: GET
    URL Params:
    Data Params: JSON
        {
            annotationid : int
                the annotationid to get the ontology parents for
        }
    Success Response:
        Code : 200
        Content :
        {
            parents : dict of (str:list of str) (detail type (i.e. 'higher in'), list of ontology terms)
        }
    Details :
        Validation:
            If an annotation is private, return it only if user is authenticated and created the curation. If user not authenticated, do not return it in the list
            If annotation is not private, return it (no need for authentication)
    
/annotations/get_full_sequences

    Title: get_full_sequences
    Description : Get all the sequences (ACGT) associated with an annotation
    URL: annotations/get_full_sequences
    Method: GET
    URL Params:
    Data Params: JSON
        {
            annotationid : int
                the annotationid to get the sequences for
        }
    Success Response:
        Code : 200
        Content :
        {
            'sequences' : list of dict
                information about each sequence in the annotation
                {
                    'seq' : str (ACGT)
                        the sequence
                    'taxonomy' : str
                        the taxonomy of the sequence (or '' if not present)
                }
        }
    Details :
        Validation:
            If an annotation is private, return it only if user is authenticated and created the curation. If user not authenticated, do not return it in the list
            If annotation is not private, return it (no need for authentication)
    
/annotations/get_sequences

    Title: get_sequences
    Description : Get all sequences ids associated with an annotation
    URL: annotations/get_sequences
    Method: GET
    URL Params:
    Data Params: JSON
        {
            annotationid : int
                the annotationid to get the sequences for
        }
    Success Response:
        Code : 200
        Content :
        {
            seqids : list of int
                the seqids for all sequences participating in this annotation
        }
    Details :
        Validation:
            If an annotation is private, return it only if user is authenticated and created the curation. If user not authenticated, do not return it in the list
            If annotation is not private, return it (no need for authentication)
    
/annotations/update

    Title: Update existing annotation
    URL: /annotations/update
    Method: POST
    URL Params:
    Data Params: JSON
        {
            "annotationId" : int
                (annotationID from AnnotationsTable)
            "annotationType" : str (optional)
                annotation type (differential expression/contaminant/etc.)
                (description from AnnotationTypesTable).
                or None to not update.
            "method" : str (optional)
                The method used to detect this behavior (i.e. observation/ranksum/clustering/etc")
                (description from MethodTypesTable)
                or None to not update.
            "agentType" : str (optional)
                Name of the program which submitted this annotation (i.e. heatsequer)
                (description from AgentTypesTable)
                or None to not update.
            "description" : str (optional)
                Free text describing this annotation (i.e. "lower in green tomatoes comapred to red ones")
                or None to not update.
            "private" : bool (optional)
                default=False
                is this annotation private
                private from AnnotationsTable
                or None to not update.
            "annotationList" : (optional) list of
                {
                    "detail" : str
                        the type of detail (i.e. ALL/HIGH/LOW)
                        (description from AnnotationDetailsTypeTable)
                    "term" : str
                        the ontology term for this detail (i.e. feces/ibd/homo sapiens)
                        (description from OntologyTable)
                }
                or None to not update.
        }
    Success Response:
        Code : 201
        Content :
        {
            "annotationId" : int
            the id from AnnotationsTable for the updated annotation
        }
    Details:
        Validation:
            annotationID exists in annotations
            User is allowed to modify the annotation (if annotation is annonymous, anyone can update,
            otherwise only the user that created the annotation can update it).
        Action:
            Update all the non-None (supplied) fields in the existing annotation.
    
/experiments/add_details

    Title: Add new experiment detail
    URL: /AddExpDetails/
    Method: POST
    URL Params:
    Data Params:
        {
            "expId" : int
                (expId from ExperimentsTable) or 0 to add a new experiment
            "private" : bool (optional)
                    default=False
                    whether the experiment should be private or public (default)
                    (private from Experiments)
            "details" : list of
            {
                "type" : str
                    the detail type (i.e. "pubmedid"/"author"/etc.)
                    (description from ExperimentTypesTable linked from ExperimentsIdentifiers)
                "value" : str
                    the detail value (i.e. "john smith"/"pmid003344"/etc.)
                    (value from ExperimentsIdentifiers)
            }
        }
    Success Response:
        Code : 201
        Content :
        {
            "expId" : int
                the expId for the experiment with the details added
                same as the data expId if it was >0
                or the expId for the new experiment created
        }
    Details:
        Validation:
            if expId>0, make sure the experiment exists
            If the detail already exists for the experiment, update it?
        Action:
            If ExpId not supplied, get a new unique experimentId (can use the current uniqueid in ExperimentsTable) and add the private field and the userID/Date
            Add entries into ExperimentsTable for all the pairs in the list. For each one, automatically add the userId and date
            Return the new expId for these details
            for each "type"/"value" in the "details" list, if "type" exists in ExperimentTypesTable, get the id and add it to "type" field in ExperimentsIdentifiers table. Otherwise, create it there and get the id and add it to "type" field in ExperimentsIdentifiers.
    
/experiments/get_annotations

    Title: Query annotations based on experiment id
    Description: Get the annotations associated with an experiment
    URL: /experimets/get_annotations
    Method: GET
    URL Params: JSON
        {
            "expId" : int
                the experiment id
        }
    Success Response:
        Code : 200
        Content :
        {
            "annotations" : list of dict:
            {
                "userid" : int
                "annotationtype" : str
                "method" : str
                "data" : str
                "agent" : str
                "description" : str
                "private" : str
            }
        }
    Details :
        Validation:
            If study is private, return only if user is authenticated and created the study. If user not authenticated, return experiment not found
            if annotation is private, return only if created by the same user as the querying
            if study not found - return error
    
/experiments/get_details

    Title: Query experiment based on experiment id
    Description: Get the details (i.e. 'pubmedid':'1665344' etc.) of experiment with a given id
    URL: /experimets/get_data
    Method: GET
    URL Params: JSON
        {
            "expId" : int
                the experiment id
        }
    Success Response:
        Code : 200
        Content :
        {
            "details" : list of
            {
                type : str
                    the field name (i.e. "pubmedid")
                value : str
                    the value of the field (i.e. "1665344")
            }
        }
    Details :
        Validation:
            If study is private, return only if user is authenticated and created the study. If user not authenticated, return experiment not found
            If study is not private, return details (no need for authentication)
            if study not found - return error
    
/experiments/get_experiments_list

    Title: get_experiments_list
    Description: Get list of all experiments in the database and their details
    URL: /experimets/get_experiments_list
    Method: GET
    URL Params: JSON
        {
        }
    Success Response:
        Code : 200
        Content :
        {
            "explist" : list of tuples:
            {
                expid : int
                details : tuples of (name, value)
            }
        }
    Details :
        Validation:
            If experiment is private, return only if user is authenticated and created the study.
    
/experiments/get_id

    Title: Query experiment based on type/value:
    Description: Get IDs of all experiments matching one of the field/value pairs (i.e. "Pubmedid","111222")
    URL: /experimets/get_id
    Method: GET
    URL Params: JSON
        {
            details : list of tuples [type,value] of str where:
                type : str
                    the detail type (i.e. "pubmedid"/"author"/etc.)
                    (type from ExperimentsTable)
                value : str
                    the detail value (i.e. "john smith"/"pmid003344"/etc.)
        }
    Success Response:
        Code : 200
        Content :
        {
            "experiments" : list of
            {
                expId : int
                    the expId for an experiment matching the query
            }
        }
    Details :
        Validation:
            If study is private, return only if user is authenticated and created the study. If user not authenticated, do not return it in the list
            If study is not private, return it (no need for authentication)
    
/experiments/get_id_by_list

    Title: Query experiment based on list of type/value:
    Description: Get IDs of all experiments matching one of the field/value pairs (i.e. "Pubmedid","111222")
                 Similar to get_id but pairs are supplied as two arrays instead of list of pairs
    URL: /experimets/get_id_by_list
    Method: GET
    URL Params: JSON
        {
            'nameStrArr': list of str
                list of field names
            'valueStrArr': list of str
                corresponding values
        }
    Success Response:
        Code : 200
        Content :
        {
            "experiment" : id
            {
                expId : int
                    the expId for an experiment matching the query
            }
        }
    Details :
        Validation:
            If study is private, return only if user is authenticated and created the study. If user not authenticated, do not return it in the list
            If study is not private, return it (no need for authentication)
    
/ontology/add

    Title: Add new ontology term
    URL: /ontology/add
    Description : Add a new term to the ontology term list and link to parent, synonyms
    Method: POST
    URL Params:
    Data Params: JSON
        {
            "term" : str
                the new term to add (description from OntologyTable)
            "parent" : str (optional)
                default="na"
                if supplied, the id of the parent of this term (description from OntologyTable)
            "ontologyname" : str (optional)
                default = "scdb"
                name of the ontology to which this term belongs (i.e. "doid")
                (description from OntologyNamesTable
            "synonyms" : (optional) list of
            {
                "term" : str
                    alternative names for the new ontology term
            }
        }
    Success Response:
        Code : 201
        Content :
        {
            "termid" : int
                the id of the new ontology term
        }
    Details:
        Validation:
        NA
        Action:
            if term does not exist in OnologyTable, add it (description in OntologyTable).
            Get the term id (id in OntologyTable)
            If parent is supplied, if it does not exist in OntologyTable, add it. Get the parentid (id from OntologyTable for the parent).
            Get the ontologynameid from the OntologyNamesTable. Add (ontologyId = termid, ontologyParentId = parentif, ontologyNameId = ontologynameid)
            for each sysnonym, if not in OntologyTable add it, get the synonymid, add to OntologySynymTable (idOntology = termid, idSynonym = synonymid)
    
/ontology/get

    Title: Return ontology id for ones that exist
    URL: /ontology/get
    Method: POST
    URL Params:
    Data Params: JSON
        {
            "ontology" : list of str
                the sequences to add (acgt)
        }
    Success Response:
        Code : 201
        Content :
        {
            "ontIds" : list of int
                id of ontologies
        }
    Details:
        Validation:
        Action:
        Get ids for list of ontologies
    
/ontology/get_all_synonyms

    Title: Query synonyms
    Description : Get all synonym descriptions
    Method: GET
    Success Response:
        Code : 200
        Content :
            "synonym" : list of
            {
                "description" : str
                    the synonym terms
            }
        }
    
/ontology/get_all_terms

    Title: Query Ontology
    Description : Get all ontology terms
    Method: GET
    Data Params: Parameters
        {
            min_term_id : int, optional
                the minimal ontology tern id to get the info for (get the term list only for ids>min_term_id)
                if not provided, get a list of all terms
            ontologyid: int, optional
                get only terms from this ontology
                if not provided, get terms from all ontologies

        }
    Success Response:
        Code : 200
        Content :
        {
            "ontology" : dict of {term(str): id(int))}
            {
                "term" : str
                    the ontology term
                "id" : int
                    the internal unique dbbact id for the term
            }
        }
    
/ontology/get_annotations

    Title: get_annotations
    Description : Get all annotations associated with an ontology term
    URL: ontology/get_annotations
    Method: GET
    URL Params:
    Data Params: Parameters
        {
            term : str
                the ontology term to get the annotations for
        }
    Success Response:
        Code : 200
        Content : JSON
        {
            "annotations" : list of
                {
                    "annotationid" : int
                        the id of the annotation
                    "userid" : int
                        The user id
                        (id from UsersTable)
                    "user" : str
                        name of the user who added this annotation
                        (userName from UsersTable)
                    "addedDate" : str (DD-MM-YYYY HH:MM:SS)
                        date when the annotation was added
                        (addedDate from CurationsTable)
                    "expid" : int
                        the ID of the experiment from which this annotation originated
                        (uniqueId from ExperimentsTable)
                        (see Query Experiment)
                    "currType" : str
                        curration type (differential expression/contaminant/etc.)
                        (description from CurationTypesTable)
                    "method" : str
                        The method used to detect this behavior (i.e. observation/ranksum/clustering/etc")
                        (description from MethodTypesTable)
                    "agentType" : str
                        Name of the program which submitted this annotation (i.e. heatsequer)
                        (description from AgentTypesTable)
                    "description" : str
                        Free text describing this annotation (i.e. "lower in green tomatoes comapred to red ones")
                    "private" : bool
                        True if the curation is private, False if not
                    "CurationList" : list of
                        {
                            "detail" : str
                                the type of detail (i.e. ALL/HIGH/LOW)
                                (description from CurationDetailsTypeTable)
                            "term" : str
                                the ontology term for this detail (i.e. feces/ibd/homo sapiens)
                                (description from OntologyTable)
                        }
                }
        }
    Details :
        Validation:
            If an annotation is private, return it only if user is authenticated and created the curation. If user not authenticated, do not return it in the list
            If annotation is not private, return it (no need for authentication)
    
/ontology/get_parents

    Title: Get all parents for a given ontology term
    URL: /ontology/get_parents
    Description : Get a list of all the parents for a given ontology term
    Method: GET
    URL Params:
        {
            "term" : str
                the ontology term to get the parents for
        }
    Data Params:
    Success Response:
        Code : 201
        Content :
        {
            "parents" : list of str
                list of the parent terms
        }
    Details:
        Validation:
        NA
        Action:
        Get all the parents of the ontology term
        If it is a synonym for a term, get the original term first.
        Note that if the term is in more than one ontology, will return all parents
    
/ontology/get_synonym

    Title: Query Ontology synonyms
    Description : Get all ontology synonyms starting from a given id
                    used to update the autocomplete list in the client
    URL: /ontology/get_synonym?startid=
    Method: GET
    URL Params:
        startid : int
            retrieve all ontology synonyms with id bigger than startid (incremental update client)
            (id from OntologySynonymTable)
    Success Response:
        Code : 200
        Content :
        {
            "terms" : list of
            {
                "id" : int
                    the synonym relation id (id from SynonymTable)
                "synonymterm" : str
                    the synonym term (description from OntologyTable linked by idSynonym from OntologySynonymTable)
                "originalterm" : str
                    the ontology term to which it is a synonym (description from OntologyTable linked by idOntology)
            }
        }
    
/ontology/get_term_pair_count

    Title: get_term_pair_count
    Description : Get statistics about ontology term pair (i.e. "feces+homo sapiens") (in how many experiments it appears)
    URL: ontology/get_term_pair_count
    Method: GET
    URL Params:
    Data Params: JSON
        {
            term_pairs : list of str
                list of ontology term pairs to get the experiment count for
        }
    Success Response:
        Code : 200
        Content :
        {
            term_count : dict of {term, float}
                The total number of experiments each term pair appears in
        }
    Details :
        Validation:
    
/ontology/get_term_stats

    Title: get_tern_stats
    Description : Get statistics about ontology terms (in how many annotations it appears)
    URL: ontology/get_term_stats
    Method: GET
    URL Params:
    Data Params: JSON
        {
            terms : list of str
                list of ontology terms to get the statistics for. Can include term pairs in the format of 'term1+term2' where term1 is alphabetically before term2
        }
    Success Response:
        Code : 200
        Content :
        {
            term_info : dict of {term, dict}
            Information about each term which appears in the annotation parents. Key is the ontolgy term. the value dict is:
            'total_annotations' : int
                total number of annotations where this term appears (as a parent)
            'total_sequences' : int
                total number of sequences in annotations where this term appears (as a parent)
        }
    Details :
        Validation:
    
/sequences/add

    Title: Add new sequences (or return seqid for ones that exist)
    URL: /sequences/add
    Method: POST
    URL Params:
    Data Params: JSON
        {
            "sequences" : list of str
                the sequences to add (acgt)
            "taxonomies" : list of str (optional)
                the taxonomy per sequence (if not provided, na will be used)
            "ggids" : list of int (optional)
                list of GreenGenes id per sample (if not provided, 0 will be used)
            "primer" : str
                name of the primer region (i.e. 'V4'). if region does not exist, will fail
        }
    Success Response:
        Code : 201
        Content :
        {
            "seqIds" : list of int
                the new sequence id per sequence in the list
        }
    Details:
        Validation:
        Action:
        Add all sequences that don't already exist in SequencesTable
    
/sequences/add_primer_region

    Title: add_primer_region
    Description : Add a new primer region (i.e. 'V4') to the primers table
    URL: /sequences/add_primer_region
    Method: POST
    URL Params:
    Data Params: JSON
        {
        'name': str
            name of the region (i.e. 'v4')
        'fprimer', 'rprimer': str, optional
            name (i.e. '515f') or sequence pf the forward and reverse primers used for the region
        }
    Success Response:
        Code : 200
        Content :
        {
            "primers": list of dict of {
                'primerid': int
                    dbbact internal id of the primer region (i.e. 1 for v4, etc.)
                'name': str,
                    name of the primer region (i.e. 'v4', 'its1', etc.)
                'fprimer': str
                'rprimer: str
                    name of the forward and reverse primers for the region (i.e. 515f, etc.)
            }
        }
    
/sequences/get_annotations

    Title: Query sequence:
    Description : Get all the annotations about a given sequence
    URL: /sequences/get_annotations
    Method: GET
    URL Params:
    Data Params: JSON
        {
            "sequence" : str
                the DNA sequence string to query the database (can be any length). Can also be a SILVA ID if dbname is set to "silva"
            "region" : int (optional)
                the region id (default=1 which is V4 515F 806R)
            "get_term_info" : bool (optional)
                True (default) to get information about all ontology predecessors of terms of all annotations of the sequence.
            "get_tax_info": book (optional)
                True (default) to get the dbbact taxonomy string of the sequence (or None if not in dbbact)
            "use_sequence_translator": bool (optional)
                True (default) to get also annotations for dbbact sequences from other regions linked to the query sequences using the wholeseqdb (i,e, SILVA)
                False to get just annotations for dbbact sequences that match exactly the queryy sequences
            "dbname": str, optional
                If supplied (i.e. 'silva'), assume sequence is the identifier in dbname (i.e.  'FJ978486' for 'silva' instead of acgt sequence)
    Success Response:
        Code : 200
        Content :
        {
            "taxonomy" : str
                the taxonomy from dbBact taxonomies (if availble).
                Not returned if get_tax_info is False
            "annotations" : list of
                {
                    "annotationid" : int
                        the id of the annotation
                    "userid" : int
                        The user id
                        (id from UsersTable)
                    "user" : str
                        name of the user who added this annotation
                        (userName from UsersTable)
                    "addedDate" : str (DD-MM-YYYY HH:MM:SS)
                        date when the annotation was added
                        (addedDate from CurationsTable)
                    "expid" : int
                        the ID of the experiment from which this annotation originated
                        (uniqueId from ExperimentsTable)
                        (see Query Experiment)
                    "currType" : str
                        curration type (differential expression/contaminant/etc.)
                        (description from CurationTypesTable)
                    "method" : str
                        The method used to detect this behavior (i.e. observation/ranksum/clustering/etc")
                        (description from MethodTypesTable)
                    "agentType" : str
                        Name of the program which submitted this annotation (i.e. heatsequer)
                        (description from AgentTypesTable)
                    "description" : str
                        Free text describing this annotation (i.e. "lower in green tomatoes comapred to red ones")
                    "private" : bool
                        True if the curation is private, False if not
                    "CurationList" : list of
                        {
                            "detail" : str
                                the type of detail (i.e. ALL/HIGH/LOW)
                                (description from CurationDetailsTypeTable)
                            "term" : str
                                the ontology term for this detail (i.e. feces/ibd/homo sapiens)
                                (description from OntologyTable)
                        }
                }
            term_info : dict of {term: dict}
            Information about all ontology terms associated with any of the annotations (including predecessors)
                key: term (str)
                value: dict of pairs:
                    'total_annotations' : number of annotations having this term in the database (int)
                    'total_sequences' : number of sequences in annotations having this term in the database (int)
        }
    Details :
        Validation:
            If an annotation is private, return it only if user is authenticated and created the curation. If user not authenticated, do not return it in the list
            If annotation is not private, return it (no need for authentication)
    
/sequences/get_fast_annotations

    Title: Get Fast Annotations
    Description : Get annotations for a list of sequences in a compressed form
    URL: /sequences/get_fast_annotations
    Method: GET
    URL Params:
    Data Params: JSON
        {
            "sequences": list of str ('ACGT')
                the list of sequence strings to query the database (can be any length). Alternatively, can be list of SILVA IDs (in case dbname is set to 'silva')
            "region": int (optional)
                the region id (default=1 which is V4 515F 806R)
            "get_term_info": bool (optional)
                True (default) to return also information about each term, False not to return
            "get_taxonomy": bool (optional)
                True (default) to get the dbbact assigned taxonomy for each query sequence
            "get_parents": bool (optional)
                True (default) to get the parent terms for each annotation ontology term, False to just get tge annotation terms
            "get_all_exp_annotations": bool (optional)
                True (default) to get all the annotations from each experiment containing one annotation with the sequence, False to just get the annotations with the sequence
            "use_sequence_translator": bool (optional)
                True (default) to get also annotations for dbbact sequences from other regions linked to the query sequences using the wholeseqdb (i,e, SILVA)
                False to get just annotations for dbbact sequences that match exactly the queryy sequences
            "dbname": str, optional
                If supplied (i.e. 'silva'), assume sequence is the identifier in dbname (i.e.  'FJ978486' for 'silva' instead of acgt sequence)
    Success Response:
        Code : 200
        Content :
        {
            annotations: dict of (annotationid: details):
                    annotationid : the annotationid used in seqannotations
                    details:
                {
                    "annotationid" : int
                        the id of the annotation
                    "user" : str
                        name of the user who added this annotation
                        (userName from UsersTable)
                    "addedDate" : str (DD-MM-YYYY HH:MM:SS)
                        date when the annotation was added
                        (addedDate from CurationsTable)
                    "expid" : int
                        the ID of the experiment from which this annotation originated
                        (uniqueId from ExperimentsTable)
                        (see Query Experiment)
                    "currType" : str
                        curration type (differential expression/contaminant/etc.)
                        (description from CurationTypesTable)
                    "method" : str
                        The method used to detect this behavior (i.e. observation/ranksum/clustering/etc")
                        (description from MethodTypesTable)
                    "agentType" : str
                        Name of the program which submitted this annotation (i.e. heatsequer)
                        (description from AgentTypesTable)
                    "description" : str
                        Free text describing this annotation (i.e. "lower in green tomatoes comapred to red ones")
                    "private" : bool
                        True if the curation is private, False if not
                    "CurationList" : list of
                        {
                            "detail" : str
                                the type of detail (i.e. ALL/HIGH/LOW)
                                (description from CurationDetailsTypeTable)
                            "term" : str
                                the ontology term for this detail (i.e. feces/ibd/homo sapiens)
                                (description from OntologyTable)
                        }
                    "parents" : list of tuples (type, list of terms)
                        {
                            type : type of the annotation type ('high'/'low','all')
                            list of terms - list of ontology terms which are annotated or parents of annotated ontology term
                        }
                }
            seqannotations : list of (seqid, annotationids):
            {
                    seqpos : position of the sequence in the list
                    annotationids : list of int
                            the annotationsid associated with this sequence
            }
            term_info : dict of {term, dict}:
            Information about each term which appears in the annotation parents. Key is the ontolgy term. the value dict is:
            {
                    'total_annotations' : int
                        total number of annotations where this term appears (as a parent)
                    'total_sequences' : int
                        total number of sequences in annotations where this term appears (as a parent)
            }
            taxonomy : list of str
            The dbbact assigned taxonomy for each sequence (ordered in the same order as query sequences)
        }
    Details :
        Return a dict of details for all the annotations associated with at least one of the sequences used as input, and a list of seqpos and the associated annotationids describing it
        (i.e. a sparse representation of the annotations vector for the input sequence list)
    Validation:
        If an annotation is private, return it only if user is authenticated and created the curation. If user not authenticated, do not return it in the list
        If annotation is not private, return it (no need for authentication)
    
/sequences/get_hash_annotations

    Title: Get hash annotation ids
    Description : Get annotation ids for hash string
    URL: /sequences/get_hash_annotations
    Method: GET
    URL Params:
    Data Params: JSON
        {
            hash : str
                the hash substring to look for
        }
    Success Response:
        Code : 200
        Content :
        {
            'annotations' : list of (annotation, counts)
                the annotation details for all annotations that contain a sequence with the requested taxonomy (see /sequences/get_annotations) and the count of taxonomy sequences with the annotation
            seqids : list on int
                list of the sequenceids that have this taxonomy in the database
        }
    Validation:
        If an annotation is private, return it only if user is authenticated and created the curation. If user not authenticated, do not return it in the list
        If annotation is not private, return it (no need for authentication)
    
/sequences/get_info

    Title: Get sequences information
    Description : Get information (sequence, taxonomy) from sequence ids
    URL: /sequences/get_info
    Method: GET
    URL Params:
    Data Params: JSON
        {
            seqids : int or list of int
                the sequence ids to get information for
        }
    Success Response:
        Code : 200
        Content :
        {
    sequences : list of dict (one per sequence). contains:
        'seq' : str (ACGT)
            the sequence
        'taxonomy' : str
            the taxonomy of the sequence or '' if unknown
        'total_annotations': int
            the number of annotations which this sequence is associated with
        'total_experiments': int
            the total number of experiments which this sequence is associated with
        }
    Validation:
    
/sequences/get_list_annotations

    Title: Query sequence:
    Description : Get all the annotations about a list of sequences
    URL: /sequences/get_annotations
    Method: GET
    URL Params:
    Data Params: JSON
        {
            "sequences": list of str ('ACGT')
                the list of sequence strings to query the database (can be any length), or alternatively silva IDs (if dbname='silva')
            "region": int (optional)
                the region id (default=1 which is V4 515F 806R)
            "use_sequence_translator": bool (optional)
                True (default) to get also annotations for dbbact sequences from other regions linked to the query sequences using the wholeseqdb (i,e, SILVA)
                False to get just annotations for dbbact sequences that match exactly the queryy sequences
            "dbname": str, optional
                If supplied (i.e. 'silva'), assume sequence is the identifier in dbname (i.e.  'FJ978486' for 'silva' instead of acgt sequence)
    Success Response:
        Code : 200
        Content :
        {
            'seqannotations': list
            list of:
                {
                "taxonomy" : str
                (taxonomy from SequencesTable)
                "annotations" : list of
                    {
                        "annotationid" : int
                            the id of the annotation
                        "user" : str
                            name of the user who added this annotation
                            (userName from UsersTable)
                        "addedDate" : str (DD-MM-YYYY HH:MM:SS)
                            date when the annotation was added
                            (addedDate from CurationsTable)
                        "expid" : int
                            the ID of the experiment from which this annotation originated
                            (uniqueId from ExperimentsTable)
                            (see Query Experiment)
                        "currType" : str
                            curration type (differential expression/contaminant/etc.)
                            (description from CurationTypesTable)
                        "method" : str
                            The method used to detect this behavior (i.e. observation/ranksum/clustering/etc")
                            (description from MethodTypesTable)
                        "agentType" : str
                            Name of the program which submitted this annotation (i.e. heatsequer)
                            (description from AgentTypesTable)
                        "description" : str
                            Free text describing this annotation (i.e. "lower in green tomatoes comapred to red ones")
                        "private" : bool
                            True if the curation is private, False if not
                        "CurationList" : list of
                            {
                                "detail" : str
                                    the type of detail (i.e. ALL/HIGH/LOW)
                                    (description from CurationDetailsTypeTable)
                                "term" : str
                                    the ontology term for this detail (i.e. feces/ibd/homo sapiens)
                                    (description from OntologyTable)
                            }
                    }
                }
        }
    Details :
        Validation:
            If an annotation is private, return it only if user is authenticated and created the curation. If user not authenticated, do not return it in the list
            If annotation is not private, return it (no need for authentication)
    
/sequences/get_primers

    Title: get_primers
    Description : Get information about all the sequencing primers used in dbbact
    URL: /sequences/get_primers
    Method: GET, POST
    URL Params:
    Data Params: JSON
        {
        }
    Success Response:
        Code : 200
        Content :
        {
            "primers": list of dict of {
                'primerid': int
                    dbbact internal id of the primer region (i.e. 1 for v4, etc.)
                'name': str,
                    name of the primer region (i.e. 'v4', 'its1', etc.)
                'fprimer': str
                'rprimer: str
                    name of the forward and reverse primers for the region (i.e. 515f, etc.)
                'fprimerseq': str
                    the concensus sequence for the forward primer
            }
        }
    
/sequences/get_string_annotations

    Title: Get sequence string annotations
    Description : Get description (string) and html link for all annotations of a given sequence
    URL: /sequences/get_string_annotations
    Method: GET, POST
    URL Params:
    Data Params: JSON
        {
            sequence : str
                the DNA sequence string to query the database (can be any length)
            region : int (optional)
                the region id (default=1 which is V4 515F 806R)
    Success Response:
        Code : 200
        Content :
        {
            "annotations" : list of
                {
                    "annotationid" : int
                        the id of the annotation
                    "annotation_summary" : str
                        String summarizing the annotation (i.e. 'higher in feces compared to saliva in homo spiens')
                }
        }
    Details :
        Validation:
            If an annotation is private, return it only if user is authenticated and created the curation. If user not authenticated, do not return it in the list
            If annotation is not private, return it (no need for authentication)
    
/sequences/get_taxonomy_annotation_ids

    Title: Get taxonomy annotation ids
    Description : Get annotation ids for taxonomy substring
    URL: /sequences/get_taxonomy_annotation_ids
    Method: GET
    URL Params:
    Data Params: JSON
        {
            taxonomy : str
                the taxonomy substring to look for
        }
    Success Response:
        Code : 200
        Content :
        {
            annotationids : list of (int, int) (annotationid, count)
                the annotation ids and number of sequences from the taxonomy appearing in that annotation *for all annotations that contain at least 1 sequence from the requested taxonomy)
            seqids : list on int
                list of the sequenceids that have this taxonomy in the database
        }
    Details :
        Returns a list of annotationids. can get the annotation details for them via another api call to sequences/get_fast_annotations or sequences/
    Validation:
        If an annotation is private, return it only if user is authenticated and created the curation. If user not authenticated, do not return it in the list
        If annotation is not private, return it (no need for authentication)
    
/sequences/get_taxonomy_annotations

    Title: Get taxonomy annotation ids
    Description : Get annotation ids for taxonomy substring
    URL: /sequences/get_taxonomy_annotation_ids
    Method: GET
    URL Params:
    Data Params: JSON
        {
            taxonomy : str
                the taxonomy substring to look for
        }
    Success Response:
        Code : 200
        Content :
        {
            'annotations' : list of (annotation, counts)
                the annotation details for all annotations that contain a sequence with the requested taxonomy (see /sequences/get_annotations) and the count of taxonomy sequences with the annotation
            seqids : list on int
                list of the sequenceids that have this taxonomy in the database
        }
    Validation:
        If an annotation is private, return it only if user is authenticated and created the curation. If user not authenticated, do not return it in the list
        If annotation is not private, return it (no need for authentication)
    
/sequences/get_taxonomy_sequences

    Title: Get taxonomy sequences
    Description : Get a list of dbbact sequences with the given taxonomy substring
    URL: /sequences/get_taxonomy_sequences
    Method: GET
    URL Params:
    Data Params: JSON
        {
            taxonomy : str
                the taxonomy substring to look for
        }
    Success Response:
        Code : 200
        Content :
        {
            'sequences' : list of dict
                information about each sequence in the annotation
                {
                    'seq' : str (ACGT)
                        the sequence
                    'seqid': int
                        the dbbact sequence id
                    'taxonomy': str
                        the taxonomy for the given sequence. semicolon separate format: k_XXX;f_YYY;...
                    'total_annotations': int
                        the number of annotations which this sequence is associated with
                    'total_experiments': int
                        the total number of experiments which this sequence is associated with
                }
        }
    Validation:
    
/sequences/get_taxonomy_str

    Title: Query sequence:
    Description : Get the dbbact stored taxonomy about a given sequence
    URL: /sequences/get_taxonomy_str
    Method: GET
    URL Params:
    Data Params: JSON
        {
            sequence : str
                the DNA sequence string to query the database (can be any length)
            region : int (optional)
                the region id (default=1 which is V4 515F 806R)
    Success Response:
        Code : 200
        Content :
        {
            "taxonomy" : str
        }
    
/sequences/getid

    Title: Get id for a given sequence (or return -1 if does not exist)
    URL: /sequences/getid
    Method: GET
    URL Params:
    Data Params: JSON
        {
            "sequence" : str
                the sequence to get data about. could be 'acgt' or SILVA ID (in case dbname is set to 'silva')
            "no_shorter" : bool (optional)
                False (default) to get also shorter sequences from DB if matching.
                True to get only sequences at least as long as the query
            "no_longer" : bool (optional)
                False (default) to get also longer sequences from DB if matching on query length.
                True to get only sequences not longer than the query
            "use_sequence_translator": bool (optional)
                True to get also ids for dbbact sequences from other regions linked to the query sequences using the wholeseqdb (i,e, SILVA)
                False (default) to get just ids for dbbact sequences that match exactly the queryy sequences
            "dbname": str, optional
                If supplied (i.e. 'silva'), assume sequence is the identifier in dbname (i.e.  'FJ978486' for 'silva' instead of acgt sequence)
        }
    Success Response:
        Code : 201
        Content :
        {
            "seqId" : list of int
                the sequence ids, or []] if doesn't exists
                Note: can be more than 1 id since may contain subsequences (if no_longer is False or no_shorter is False) or different regions (if use_sequence_translator=True)
        }
    Details:
        Validation:
        Action:
    
/sequences/getid_list

    Title: Get dbbact ids for a list of given sequences
    URL: /sequences/getid_list
    Method: GET
    URL Params:
    Data Params: JSON
        {
            "sequences" : list of str
                the list of sequences to get data about
            "no_shorter" : bool (optional)
                False (default) to get also shorter sequences from DB if matching.
                True to get only sequences at least as long as the query
            "no_longer" : bool (optional)
                False (default) to get also longer sequences from DB if matching on query length.
                True to get only sequences not longer than the query
            "use_sequence_translator": bool (optional)
                True to get also annotations for dbbact sequences from other regions linked to the query sequences using the wholeseqdb (i,e, SILVA)
                False (default) to get just annotations for dbbact sequences that match exactly the query sequences
            "dbname": str, optional
                If supplied (i.e. 'silva'), assume sequence is the identifier in dbname (i.e.  'FJ978486' for 'silva' instead of acgt sequence)
        }
    Success Response:
        Code : 201
        Content :
        {
            "seqIds" : list of list of int
                the sequence ids matching each original sequence,
                Note: can be more than 1 id per sequence since we are looking for subsequences
        }
    Details:
        Validation:
        Action:
    
/sequences/guess_region

    Title: guess_region
    Description : Suggest the primer region for the list of sequences
    URL: /sequences/guess_region
    Method: GET
    URL Params:
    Data Params: JSON
        {
            "sequence": list of str
                the sequences (ACGT) to get the primer region for
        }
    Success Response:
        Code : 200
        Content :
        {
            "region": str
                name of the primer region containing all the sequences matching dbbact
            "regionid": int
                id of the primer region
        }
    
/stats/stats

    Title: Get statistics about the database
    URL: /stats/stats
    Method: GET
    URL Params:
    Data Params:
     Success Response:
        Code : 201
        Content :
        stats : dict
        {
            "NumSequences" : int
                number of unique sequences in the sequenceTable (each sequence can appear in multiple annotations)
            "NumAnnotations" : int
                number of unique annotations (each annotation contains many sequences)
            "NumSeqAnnotations" : int
                number of sequence annotations in the sequenceTable
            "NumOntologyTerms" : int
                number of ontology terms in the OntologyTable
            "NumExperiments" : int
                number of unique expIDs in the ExperimentsTable
            "Database": str
                name of current database for which the stats are returned
        }
    Details:
    
/users/forgot_password

    Title: send passowrd via mail
    URL: /users/forgot_password
    Method: POST
    URL Params:
    Data Params: JSON
        {
            'user' : str
                user name
        }
    Success Response:
        Code : 201
        Content :
        {
            "status" : 1
        }
    Details:
        Validation:
        Action:
    
/users/get_user_annotations

    Title: Get user annotations
    Description : Get all the annotations created by a user
    URL: /sequences/get_user_annotations
    Method: GET
    URL Params:
    Data Params: JSON
        {
            foruserid : int
                the userid to get the annotations created by
    Success Response:
        Code : 200
        Content :
        {
            'userannotations': list
            list of:
                {
                "taxonomy" : str
                (taxonomy from SequencesTable)
                "annotations" : list of
                    {
                        "annotationid" : int
                            the id of the annotation
                        "user" : str
                            name of the user who added this annotation
                            (userName from UsersTable)
                        "addedDate" : str (DD-MM-YYYY HH:MM:SS)
                            date when the annotation was added
                            (addedDate from CurationsTable)
                        "expid" : int
                            the ID of the experiment from which this annotation originated
                            (uniqueId from ExperimentsTable)
                            (see Query Experiment)
                        "currType" : str
                            curration type (differential expression/contaminant/etc.)
                            (description from CurationTypesTable)
                        "method" : str
                            The method used to detect this behavior (i.e. observation/ranksum/clustering/etc")
                            (description from MethodTypesTable)
                        "agentType" : str
                            Name of the program which submitted this annotation (i.e. heatsequer)
                            (description from AgentTypesTable)
                        "description" : str
                            Free text describing this annotation (i.e. "lower in green tomatoes comapred to red ones")
                        "private" : bool
                            True if the curation is private, False if not
                        "CurationList" : list of
                            {
                                "detail" : str
                                    the type of detail (i.e. ALL/HIGH/LOW)
                                    (description from CurationDetailsTypeTable)
                                "term" : str
                                    the ontology term for this detail (i.e. feces/ibd/homo sapiens)
                                    (description from OntologyTable)
                            }
                    }
                }
        }
    Details :
        Validation:
            If an annotation is private, return it only if user is authenticated and created the annotation. If user not authenticated, do not return it in the list
            If annotation is not private, return it (no need for authentication)
    
/users/get_user_id

    Title: Get user id from user/password
    URL: users/get_user_id
    Method: POST
    URL Params:
    Data Params: JSON
        {
            user : str
                user name
            pwd : str
                password
        }
    Success Response:
        Code : 200
        Content :
        {
            user : int
                the userid (0 for anonymous if user and pwd are empty)
        }
    
/users/get_user_public_information

    Title: Return the user information
    URL: users/get_user_public_information
    Method: POST,GET
    Data Params: JSON
        {
            username : str
                the dbbact username
        }
    Success Response:
        Code : 200
        Content :
        {
            data: dict
                the user data. includes:
                'id' : int
                'username' : str
                'name' : str
                'description' : str
                'email' : str
                    if shared, returns email, otherwise returns "-"
        }
    
/users/recover_password

    Title: send passowrd via mail
    URL: /users/recover_password
    Method: POST
    URL Params:
    Data Params: JSON
        {
            'user' : str
                user name
        }
    Success Response:
        Code : 201
        Content :
        {
            "status" : 1
        }
    Details:
        Validation:
        Action:
    
/users/register_user

    Title: register new user
    URL: /users/register_user
    Method: POST
    URL Params:
    Data Params: JSON
        {
            'user': str
                user name
            'pwd': str,
                password
            'name': str
                name (optional)
            'description': str
                description (optional)
            'email': str
                email address
            'publish': 'y' or 'n'
                publish user email
        }
    Success Response:
        Code : 201
        Content :
        {
            "status" : 1
        }
    Details:
        Validation:
        Action:
    
/users/test_user_login

    Title: test user login
    URL: users/test_user_login
    Method: POST/GET