Skip to end of metadata
Go to start of metadata

cURL and the Sauce Labs API Methods Examples

The example methods for accessing the Sauce Labs API use cURL commands. cURL (originally meaning "See URL") is a free, open-source tool, that, along with libcurl as the client-side transfer library, supports HTTP API requests such as GET and POST.  You can use cURL at the command line to interact with the Sauce Labs API, or you can use cURL commands within a script. The cURL website includes a complete tutorial on how to get started with HTTP scripting, but the Sauce Labs documentation also includes extensive examples of how to use cURL commands to access API methods. 

cURL and libcurl come pre-installed with OS X and Linux, and if you wanted to use the examples in this wiki to access the Sauce Labs API, all you would need to do is open a terminal, paste in the command with your authentication credentials, and hit Enter to execute the API call. If you are using a Windows machine, the situation is a little tricker, since cURL is a utility that you have to download and install. While the native PowerShell command line tool for Windows includes the CmdLets Invoke-RestMethod and Invoke-WebRequest for accessing APIs, these are only available if you are using PowerShell 3.0, and the interaction with the Sauce Labs API has not been fully tested. For these reasons, the Sauce Labs recommendation for Windows users is to set up cURL on your machine, and then use the example cURL commands in the API documentation to construct your API calls. 

Setting Up cURL on a Windows Machine

  1. Go to http://curl.haxx.se/dlwiz/?type=bin and download the latest Windows version of cURL. 
  2. After downloading the .msi file, click it to start the installation process.

To run cURL on the command prompt, you need to set the path of the curl.exe to the PATH environment variable.

  1. Click Windows Start
  2. In the Search Programs and Files field, enter Environment Variables, and then click Edit the system environmental variables.
    This will open the System Properties dialog.
  3. In the System Properties dialog, click Environment Variables.
    This opens the Environment Variables dialog. 
  4. In the System Variables section of the Environment Variables, scroll until you find the PATH variable, and then double-click on the variable to open the Edit System Variable dialog.
  5. In the Variable Value section, add the path to curl.exe (for example, C:\Program Files\cURL\bin) to the variable value section, and then click OK.
  6. Click OK in the Environment Variables dialog to close it, and then close the System Properties dialog window.
  7. Open a new command prompt and enter curl.
    You should see something like this to verify that curl has been successfully added to the PATH variable: curl: try 'curl --help' or 'curl --manual' for more information

Differences in Syntax for Windows and OS X cURL Commands

Because of differences in the underlying operating systems, there are some differences in the syntax for cURL commands issued from within Windows and OS X. In most cases, the examples provided for OS X will also work for Windows, but where there are differences you will see both OS X and Windows examples in the Example Request column for the various types of API methods. in creating your own commands, these are a few things you should be aware of:

  • Single quotes (') do not work in Windows cURL. For commands that need them, you would need to use double quotes (")
  • For some API calls, the quotes that are inside brackets ('{') need to be escaped by a backslash (\). For example, if you wanted to run the Change Job Status API call on Windows, the call would look like this:
Example Windows cURL Syntax
curl -X PUT -u %SAUCE_USERNAME%:%SAUCE_ACCESS_KEY% -H "Content-Type: application/json" -d "{\"passed\":(value)}" https://saucelabs.com/rest/v1/%SAUCE_USERNAME%/jobs/YOUR_JOB_ID