VIOLIN Logo
VIOLIN Banner
Search: for Help
About
Introduction
Statistics
VIOLIN News
Your VIOLIN
Register or Login
Submission
Tutorial
Vaccine & Components
Vaxquery
Vaxgen
VBLAST
Protegen
VirmugenDB
DNAVaxDB
CanVaxKB
Vaxjo
Vaxvec
Vevax
Huvax
Cov19VaxKB
VaxCT
Host Responses
VaximmutorDB
VIGET
Vaxafe
Vaxar
Vaxism
Vaccine Literature
VO-SciMiner
Litesearch
Vaxmesh
Vaxlert
Vaccine Design
Vaxign2
Vaxign
Community Efforts
Vaccine Ontology
ICoVax 2012
ICoVax 2013
Advisory Committee
Vaccine Society
Vaxperts
VaxPub
VaxCom
VaxLaw
VaxMedia
VaxMeet
VaxFund
VaxCareer
Data Exchange
V-Utilities
VIOLINML
Help & Documents
Publications
Documents
FAQs
Links
Acknowledgements
Disclaimer
Contact Us
UM Logo

VIOLIN Programming Utilities (V-Utilities)

VIOLIN V-Utilities provides read-only programmatic access to pathogen, vaccine, host-response, and gene data in the VIOLIN database.

Three interfaces are available:

  • REST API v2 — recommended for new applications
  • Legacy GET/XML API — retained for backward compatibility
  • Legacy SOAP service — retained for backward compatibility

REST API v2

The REST API is a versioned, anonymous, read-only interface. It supports JSON and XML responses, pagination, standard HTTP status codes, and per-client-IP rate limiting.

Base URL: https://violinet.org/v-utilities/api/v2/

Response formats

JSON is returned by default. XML can be requested using the format query parameter:

  • ?format=json
  • ?format=xml

Clients may also use the HTTP Accept header:

  • Accept: application/json
  • Accept: application/xml
Read-only access

The REST API does not permit database modifications. The supported HTTP methods are:

  • GET
  • HEAD
  • OPTIONS

Requests using POST, PUT, PATCH, or DELETE are rejected with 405 Method Not Allowed.

Rate limit

Anonymous REST API requests are limited to 60 requests per minute per client IP address. Rate-limit information is returned in the following HTTP response headers:

  • RateLimit-Limit
  • RateLimit-Remaining
  • RateLimit-Reset
  • Retry-After, when the limit has been exceeded

A client that exceeds the limit receives 429 Too Many Requests.

Pagination

Collection endpoints support the following parameters:

  • page — page number; default: 1
  • per_page — records per page; default: 25; maximum: 100

Collection responses include a meta object containing the page number, page size, number of returned records, and total number of matching records.

REST API endpoints

API information

GET /v-utilities/api/v2/

Example:
https://violinet.org/v-utilities/api/v2/

Retrieve a pathogen

GET /v-utilities/api/v2/pathogens/{pathogen_id}

JSON example:
https://violinet.org/v-utilities/api/v2/pathogens/32?format=json

XML example:
https://violinet.org/v-utilities/api/v2/pathogens/32?format=xml

Search and list pathogens

GET /v-utilities/api/v2/pathogens

Supported parameters:

  • name — literal substring of the pathogen name
  • taxonomy_id — exact taxonomy identifier
  • page
  • per_page
  • format

Examples:
https://violinet.org/v-utilities/api/v2/pathogens?page=1&per_page=5&format=json
https://violinet.org/v-utilities/api/v2/pathogens?name=VEE&format=json
https://violinet.org/v-utilities/api/v2/pathogens?taxonomy_id=11036&format=json

The name parameter searches the pathogen-name field, not disease names or descriptions.

Retrieve vaccines associated with a pathogen

GET /v-utilities/api/v2/pathogens/{pathogen_id}/vaccines

Example:
https://violinet.org/v-utilities/api/v2/pathogens/13/vaccines?page=1&per_page=10&format=json

This endpoint is the REST equivalent of the legacy request:

fpathogen.php?ptg=p_13&datafield=vaccine&returntype=ndr

Retrieve a vaccine

GET /v-utilities/api/v2/vaccines/{vaccine_id}

JSON example:
https://violinet.org/v-utilities/api/v2/vaccines/36?format=json

XML example:
https://violinet.org/v-utilities/api/v2/vaccines/36?format=xml

Search and list vaccines

GET /v-utilities/api/v2/vaccines

Supported parameters:

  • name — literal substring of the vaccine name
  • pathogen_id — exact VIOLIN pathogen ID
  • type — exact vaccine type
  • status — exact vaccine status
  • page
  • per_page
  • format

Examples:
https://violinet.org/v-utilities/api/v2/vaccines?page=1&per_page=5&format=json
https://violinet.org/v-utilities/api/v2/vaccines?name=F1&format=json
https://violinet.org/v-utilities/api/v2/vaccines?pathogen_id=32&page=1&per_page=5&format=json
https://violinet.org/v-utilities/api/v2/vaccines?status=Licensed&page=1&per_page=5&format=json

Retrieve host responses for a vaccine

GET /v-utilities/api/v2/vaccines/{vaccine_id}/host-responses

Example:
https://violinet.org/v-utilities/api/v2/vaccines/36/host-responses?page=1&per_page=5&format=json

Deleted host-response records are excluded. The REST field persistence uses the corrected spelling of the legacy SOAP field persistance.

Retrieve a gene

GET /v-utilities/api/v2/genes/{gene_id}

Example:
https://violinet.org/v-utilities/api/v2/genes/1?format=json

The standard gene response contains gene metadata. Large DNA and protein sequences are not returned by default. The response indicates whether DNA and protein sequences are available.

REST API status codes
Status Meaning
200 OK The request completed successfully.
204 No Content An OPTIONS request completed successfully.
400 Bad Request A query parameter or value is invalid.
404 Not Found The route or requested record was not found.
405 Method Not Allowed A database-modifying HTTP method was requested.
406 Not Acceptable The requested response format is not supported.
429 Too Many Requests The per-client-IP rate limit was exceeded.
500 Internal Server Error The API could not complete the request.
503 Service Unavailable A required API component is temporarily unavailable.

Legacy GET/XML API

The original GET/XML endpoints remain available for backward compatibility. New integrations should use REST API v2.

Query by pathogen

Endpoint: https://violinet.org/v-utilities/fpathogen.php

Parameters:

  • ptg — pathogen identifier:
    • p_ followed by a VIOLIN pathogen ID
    • n_ followed by a pathogen name
    • t_ followed by a taxonomy ID
  • datafield — requested data category or field
  • returntype — legacy field-selection letters for list-style results

Examples:
https://violinet.org/v-utilities/fpathogen.php?ptg=p_32&datafield=introduction
https://violinet.org/v-utilities/fpathogen.php?ptg=p_13&datafield=vaccine&returntype=ndr

Query by vaccine

Endpoint: https://violinet.org/v-utilities/fvaccine.php

Parameters:

  • vacn — vaccine identifier:
    • v_ followed by a VIOLIN vaccine ID
    • n_ followed by a vaccine name
  • datafield — requested data category or field
  • returntype — legacy field-selection letters for list-style results

Examples:
https://violinet.org/v-utilities/fvaccine.php?vacn=v_36&datafield=description
https://violinet.org/v-utilities/fvaccine.php?vacn=v_36&datafield=host_response&returntype=vtd

The legacy interfaces preserve old parameter names and field-code behavior for existing clients. Some legacy field codes are ambiguous; new software should use the explicit field names and resource URLs provided by REST API v2.


Legacy SOAP web service

The VIOLIN SOAP service remains available for existing SOAP clients. The Web Services Description Language (WSDL) document defines the available operations and message formats.

WSDL: https://violinet.org/v-utilities/wsutil.wsdl

SOAP endpoint: https://violinet.org/v-utilities/wsutil.php

Available SOAP operations:

  • fpathogen
  • fvaccine

The SOAP namespace remains http://www.violinet.org/v-utilities/ for backward compatibility. This namespace is an identifier; SOAP requests are transmitted to the HTTPS endpoint shown above.


Additional resources

An OpenAPI specification and an AI-oriented Model Context Protocol interface are planned for a later release.