Sierra Web Service 2.0

A web service to allow individuals and institutions to interact programatically with the HIVDB program

Introduction

We currently have two web service versions to allow individuals and institutions to interact with the HIVDB drug resistance interpretation program through an API:

Sierra Web Service 2.0: 2016 – present

Sierra Web Service 2.0 is a GraphQL-based web service which outputs JSON results. This page summarizes how to use this web service. It is preferable to version 1.1 because it is actively maintained. It is also easier to begin using and to customize. For now users do not need to register for this web service. Users can write a software client in any language that provides web service libraries. We currently have one client library in Python and will be creating additional ones in Java and Perl in the upcoming weeks.

Sierra Web Service 1.0/1.1: 2005 – 2017

Sierra Web Service 1.1 is a SOAP web service which outputs XML results. Users must register with us to obtain a key which they then submit with their sequence requests. Users also require a software client which wraps the connection to the server running the web service and software to parse the XML output. Users can write a software client in any language that provides web service libraries. However, we have provided two client libraries in Java and Perl.

Usage

With the powerful query language GraphQL, Sierra Web Service 2.0 allows users/clients to obtain data and customize data schema to exactly what they need. It is easy to make requests to a GraphQL server and there are plenty of GraphQL client libraries in many languages. To assist users, we have already provided one client library written in Python. Additionally, if you would like to create your own data schema (i.e., one that differs from the default all-encompassing schema), we have set up an in-browser Editor that helps you to create variations on the default schema.

Python Client

SierraPy, the Python client provides a handy command line tool that allows users to obtain analysis reports for sequences or mutations. Default data schemas are shipped with this client and are accessible at GitHub. SierraPy also contains a SierraClient class for Python developers.

Your computer must have Python (2.7 or 3.5) and the package management tool pip installed. Once you get the prerequisites installed, just type this command to install SierraPy:

Please visit SierraPy’s readme page for the usage of command line tool.

In-Browser Editor

This editor utilizes GraphiQL, an in-browser IDE for GraphQL, which provides an interactive interface for users to view our API and then customize their data schema. Here are two example queries for users to get started:

  1. Example for sequence analysis. This example accepts several sequences as the input and returns the sequence alignments, quality assessments, pretty pairwise alignments, and drug resistance interpretations from the web service.
  2. Example for mutations analysis. This example accepts several mutations as the input and returns the quality assessments and drug resistance interpretations from the web service.

Minimal Working Examples

JavaScript (ECMAScript 6)

Python with SierraPy Client

Python with Requests

Logging and Privacy Policy

Our policy is based on the NLM's policy.

Stanford HIV Resistance Database provides web services and related pages as a public service to educational institutions. We do not collect personal information about you when you visit our sites unless you choose to provide that information to us.

Information Collected and Stored Automatically

Of the information we learn about you from your visit to our sites or access our services, we store only the following: the IP address from which you access the Internet, the date and time, the Internet address of the website from which you linked directly to our site, and the browser or client used to access our server. This information is used to measure the number of visitors to the various sections of our site and identify system performance or problem areas. We also use this information to help us expand the coverage of the sites and to make the site more useful. Stanford HIV Resistance Database periodically deletes its web logs.

Personally Provided Information

If you choose to provide us with personal information by sending an email, or by filling out a form with your personal information and submitting it through our website, we use that information to respond to your message and to help us provide you with information or material that you request. The personal information provided will be kept confidential and will not be made available to third parties.