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)
- DS_webservices_java1.5.zip (780 KB) Requires Java 1.5 or greater
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.
- pslc_datashop_message.xsd — Last updated December 2010.
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
- 2. Package Organization
- 3. How to Call a Web Service Programmatically
- 4. How to Call a Web Service from the Command Line
- 5. Version Information
- 6. Other Programming Languages
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:
||Javadocs for the web services client.|
||Contains the datashop-webservices.jar file.|
||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
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");
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.
getService method returns the output of a web
service call as a String. In this example, the complete URL being accessed is
To access a different web service, use the part that comes after
https://pslcdatashop.web.cmu.edu/services in the API documentation
"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
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.