Downloads / Web Services

Web Services provide a way to enable your program or web site to retrieve DataShop data and (in a future release) insert data back into the central repository programmatically. Our service follows the REST guidelines, which means that requests to web services are done over HTTP using URLs that represent resources.

Web Services API Status

As of October 2012, the following functions are available through web services:

  • Query the list of datasets in DataShop and get their metadata
  • Query the list of samples for a dataset in DataShop and get their metadata
  • Retrieve transactions
  • Retrieve student-step records
  • Add, retrieve, and delete external analyses

Sample Java Client

We've written a small command-line application in Java that prints the results of URL requests to the console. If you are considering writing an application in Java to interface with DataShop, browse the source for this program, which is included in the download.

Download the Sample Java Client (includes source)

Documentation for this application

Web Services XML Schema

Use this XML schema file as documentation for the format of responses from DataShop and to validate requests you make to DataShop web services.

API

Documentation for the application programming interface to DataShop Web Services.

Download the API / User's Guide

Web Services API v0.3 — PDF (396 KB)

Sample Java Client Documentation

1. Introduction

DataShop Web Services let you access DataShop data programmatically. By sending a HTTP GET request to a URL, you can get information about datasets and samples in XML format, and retrieve transaction or student-step records in a tab-delimited format. The returned XML is structured according to the pslc_datashop_message.xsd schema.

This package includes a DatashopClient class to make accessing DataShop web services more convenient, described in How to Call a Web Service below.

To use web services, you need a DataShop account, a public access key ID to identify you, and a secret key used to authenticate that a request really comes from you. If you don't already have a DataShop account, you can create one for free as described here. Once you have a DataShop account, you can create access keys by visiting this web services page.

2. Package Organization

The DataShop Web Services package is organized in the following manner:

api/: Javadocs for the web services client.
dist/: Contains the datashop-webservices.jar file.
xml/: Contains the DataShop Web Services XML schema.
/: Contains a readme.html file and the webservices.properties template.

3. How to Call a Web Service Programmatically

You can call a web service from your Java program with the DatashopClient class. First, include datashop-webservices.jar on your classpath. Then you can call a web service by following the example in this code snippet.

import edu.cmu.pslc.datashop.webservices.DatashopClient;
...
String apiToken = MY_API_TOKEN;
String secret = MY_SECRET_KEY;
String rootURL = "https://pslcdatashop.web.cmu.edu";
String servicePath = "/datasets/1";

DatashopClient client = new DatashopClient(rootURL, apiToken, secret);
String datasetXml = client.getService(servicePath, "text/xml");

The DatashopClient constructor takes your public API token and secret key as the second and third parameters. The first parameter is the part of the web services URL before "/services". This allows you to make multiple web service calls without having to specify this part of the address every time.

The getService method returns the output of a web service call as a String. In this example, the complete URL being accessed is https://pslcdatashop.web.cmu.edu/services/datasets/1. To access a different web service, use the part that comes after https://pslcdatashop.web.cmu.edu/services in the API documentation as the servicePath argument.

The "text/xml" argument specifies the MIME type format you want to receive. It indicates that the result of this call will be an XML message containing the dataset data. As of now, text/xml is the only valid value for dataset and sample web service requests.

4. How to Call a Web Service from the Command Line

You can also access web services directly from the command line. The first step is to edit webservices.properties file in the package root directory to set your public API token and secret key. The initial contents should be

api.token=YOUR_API_TOKEN
secret=YOUR_SECRET_KEY

Replace YOUR_API_TOKEN with your actual token string and YOUR_SECRET_KEY with your actual secret key and save the file. Note that the webservices.properties file must be in the directory from which you will run the program. From the command line, cd to the package root directory. Now you can call a web service like this:

java -jar dist/datashop-webservices.jar "https://pslcdatashop.web.cmu.edu/services/datasets/1"

The results of calling the service will be printed to standard output. The quotes around the URL are recommended because the shell might try to interpret some URL characters. Note also that when calling a web service from the command line, the entire URL must be specified.

Note: If you see an error such as Unable to access jarfile datashop-webservices.jar, make sure your current working directory is the package root containing a "dist" directory and a webservices.properties file.

5. Version Information

To get the version of the jar file, execute the following command on a single line:

java -classpath dist/datashop-webservices.jar
edu.cmu.pslc.datashop.util.VersionInformation

6. Other Programming Languages

Right now, we only have client code for Java. If you would like to access web services from another programming language, please contact us.

Constructing HTTP requests to access the services should be relatively straightforward. Signing each request so that it will properly authenticate you, however, is more complex. We can help you implement the authentication part, and also advise you on constructing valid HTTP requests for accessing web services from your preferred programming language.