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:
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:
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:
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.