All instructions related to Swagger require you to first authenticate yourself whenever you’ve opened a window with the Swagger UI. Below are detailed instructions on how to make sure you are fully authenticated when using Swagger API functions, and some troubleshooting tips to keep you on track.
When does authorization expire?
Opening new tabs, running into errors/failures, refreshing your page, or letting enough time go by can all cause your authentication to expire. If you're getting errors (especially 401 errors or any kind of "unauthorized" errors), try to re-authenticate using the instructions below.
Step 1. Authenticate your credentials on Swagger
1.1. Go to the Swagger UI page for the service that you want to access via API. Note that TDR and notebooks have separate Swagger pages!
TDR and notebooks Swagger pages
- Terra Data Repository
Find API endpoints for the TDR (where you'll find the commands necessary for ingesting data) at https://data.terra.bio/swagger-ui.html. - Notebooks
For notebooks, API commands for doing things like creating or deleting virtual machines or persistent disks can be found at notebooks.firecloud.org.
1.2. Click the Authorize button at the right, near the top of the page.
1.3. Check off the top three boxes in the scopes section of the pop-up and click Authorize again.
If you are creating a Terra Billing profile, you will need to click all four scopes.
1.4. If asked, select the email associated with the Billing Project that you'll be using to create the cloud environment.
What to expect
After you've clicked "Authorize" and selected your login credentials (you may be asked for a password), you'll see the pop-up below. Make sure to click "close" and not "log off" to stay authenticated as you execute the API functions.
Getting errors and failures using Swagger? If you're already using Swagger, and you notice you're starting to get a lot of errors and failures, try refreshing the browser page, and continue following these instructions.
Step 2. Execute API functions
You can now use the API functions listed on the page. Note that the email you authenticated must be the same email you use to log into Terra. This should automatically be true if you are working in the same Chrome browser window.
2.1. Select the function of interest to expand the details.
2.2. Click Try it out to activate the fields.
2.3. Fill in the request body and other fields.
2.4. Click Execute.
What to expect
If you've done everything right, you should get a 200 message in the response field, as well as whatever output the API is supposed to return.
Troubleshooting
401 errors
If you get a response that includes the word unauthorized, you likely need to re-authorize Swagger following the directions above.
If you don't know if the job is finished
Some Swagger jobs take a long time to complete, and it is hard to tell if it is stuck, failed, or still running. If that's the case, you can use the jobs APIs to check on the status.
1. Get the Swagger job ID
Use the enumerateJobs endpoint to get the Swagger job UUID.
2. Get the job status
Use the retreiveJob endpoint to get the status of the job. You will use the UUID from step one in the ID field (under parameters).