API Quick Start Guide

Please see below for instructions on registering for a Specimen Resource Locator (SRL) account and getting setup to use the API to enter your data.

Account Registration

• On the SRL homepage, click the "How to Add a Collection" button in the "Quick Links" section on the right of the page.
• Fill in the form and click the "Submit Inquiry" button at the bottom of the form once you are finished.
• If successful, you will see the following message at the top of the SRL homepage: "Your resource inquiry has been submitted. You will be contacted with further instructions upon review of your inquiry."
• After a site administrator has reviewed and approved your inquiry, you will receive an email from SRL with the subject "SRL: Resource Inquiry Approved". Click the link provided in the email and you will be taken to the account registration page on the SRL site.
• Fill in the form and click the "Create Account" button at the bottom of the form once you are finished.
• If successful, you will automatically be logged in and will see the following message at the top of your "Manage Resources" page: "Thanks for registering!"
• At this point, you have successfully registered and may now begin using the SRL API!

API Information

• Navigate to the SRL API homepage to view a browsable version of the API. You may click the "OPTIONS" button to view the fields and HTTP request types that are supported for each URL in the API. An example Python script is provided on the API homepage which demonstrates a programmatic approach to interacting with the API.
• The SRL API is a JSON RESTful API.
• When programmatically interacting with the API (via Python or another programming language, cURL commands, etc.), authentication is token-based using JSON Web Token Authentication. Before submitting any data via the API, you must first obtain a token. Subsequent requests provide the token as an HTTP request header.
• To obtain a token, request one from the API. Using cURL as an example (replace <username> and <password> below with the username and password you created during account registration earlier):

  • curl -X POST -H "Accept: application/json; indent=4" -H "Content-Type: application/json" -d '{"username": "<username>", "password": "<password>"}' https://specimens.cancer.gov/api/token-auth/

• The API will respond with your token, similar to the one below:

  • {"token":"eyJhbGciOiJIUzI1MiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6InRlc3RBUEkiLBJvcmlnX2lhdCI6MTQ1MDE5NzQ4MSwidVNlcl9pZCI6MzEsImVtYWlsIjoidGVzdEFPSUBpbXN3ZWIuY29tIiwiZXhwIjoxNDTwMjAxMDgxfQ.rrYFnem3fuUTWeTtE6cF7Ikfw2IkpGlJ7YvtIh3Z-wE"}

  • Note that your token is valid for 1 hour.
• Now that you have a token, you may submit data using the API. Simply provide your token as an HTTP request header. For example, the following request would POST a new Resource (replace <token> below with your token):

  • curl -X POST -H "Accept: application/json; indent=4" -H "Content-Type: application/json" -H "Authorization: JWT <token>" -d '{"name": "New Resource", "contact": "John Smith", "title": "Researcher", "phone": "(555) 867-5309", "email": "smithj@example.com", "address": "Address goes here", "fax": "(555) 867-5309", "url": "http://www.example.com/", "service_shipping_fee": false, "publications": [], "type": "Other", "collections": []}' https://specimens.cancer.gov/api/resource/

  • Note that the token is prefixed with "JWT ". This is required.
• Note that GET requests do not require authentication. For example, you could use the following command to receive a list of all Resources in the SRL:

  • curl -H "Accept: application/json; indent=4" -H "Content-Type: application/json" https://specimens.cancer.gov/api/resource/

Preventing Data Loss

• When updating a Resource or Collection using the API, the Resource or Collection will be entirely replaced by the update data. No partial updating of either a Resource or Collection is possible. For example, to update the "organ_site" field for a Collection, all Collection data must be provided alongside the updated value for "organ_site", or the excluded field values will be empty after the update occurs. To modify a single field, it is recommended to first retrieve the Resource or Collection using the API, and then modify the retrieved data. Resources MUST be updated INCLUDING ALL MEMBER COLLECTIONS or the collections will be DELETED.

"Staging" Status

• Brand new Resources and Collections are "staged" and must be approved by a site administrator before they will appear on the site. Previously added Resources and Collections may be modified using the API and their updates will appear live immediately.