cURL is a command line tool you can use to transfer data over a variety of protocols, for those users of *nix based systems, this tool will be very familiar.

Installation

cURL is available for MANY operating systems – you can find a download for your platform here:

http://curl.haxx.se/download.html

Also, on many *nix platforms, cURL will already be installed for you.

If downloading cURL for windows, you will normally recieve a zip file containing a single file “curl.exe”, you need to save curl to a folder on your system, such as c:\tools\curl\, and then you need to update your PATH environment variable to include the c:\tools\curl path.

(For windows users, you can configure your path via Start -> Control Panel -> System -> Advanced System settings -> Environment Variables, and then updating the “Path” system variable, appending the directory where curl.exe is stored to the end of the path value, prefixed with a semicolon e.g. <existing path>;c:\tools\curl)

This is a …
Once you have configured the path, you can start a command prompt/shell, where you can execute curl commands.

Simple Example

As a simple example, cURL can be used for retrieving a file – so for instance typing:

curl www.catchsoftware.com

Will retrieve and display the HTML that makes up the www.catchsoftware.com website in a flurry of scrolling on the console.

If we were to try and retrieve some data from the ET API though using this method, we will get nothing back:

curl http://localhost/EnterpriseTester/api/projects

If we pass some additional switches to curl, we can see why it’s not working:

curl -IL http://localhost/EnterpriseTester/api/projects
HTTP/1.1 401 Unauthorized
Date: Thu, 06 Sep 2012 22:53:26 GMT
X-AspNet-Version: 4.0.30319
X-UA-Compatible: IE=8,chrome=1
Cache-Control: no-cache
Pragma: no-cache
Expires: -1
Content-Length: 0
Connection: Close

We have recieved a 401 Unauthorized response, this is because you must authenticate with Enterprise Tester to be able to access the API – to do this with cURL the easiest option is to use what’s called “Basic” auth, allowing us to just provide our ET username/password as part of the request (notice username and password is seperated with a colon).

curl -u apiuser:apipassword http://localhost/EnterpriseTester/api/projects
{
  "Items": [
    {
      "Id": "32fe85fc-c4f0-4da3-a69a-a0c30009e914",
      "Name": "Project X",
      "OrganisationId": "3eff1489-e021-42b1-8a7d-a0be00bbe459",
      "OrganisationName": "Catch Software",
      ....

But curl can do more then just make requests, it can also support other HTTP methods such as PUT, POST and DELETE.

POST is the equivalent of an insert/create – this can represent creating a physical entity, such as a script or requirement, to the creation of some more abstract resource, such as a background task which you wish to be executed on the server (in this case the resource is representing the background normally provides access to progress and success information).

Because cURL is suitable for being executed in an unattended fashion, this makes it possible to automate simple tasks such as re-indexing – this is useful if you have a background process which may be directly adding or updating data in the Enterprise Tester database, requiring a re-index within ET for the information to be visible.

Let’s take a look at that now – first off, we must craft a suitable json request – using notepad, or your favourite text editor, create a file with the following contents:

{ 
	"Type": "Reindex", 
	"Parameters": { 
		"Optimize": true		
	}
}

And save it as “reindex_all.json”, we can now execute the following cURL command:

curl -i -H "Content-Type: application/json" -X POST -d @reindex_all.json -u apiuser:apipassword http://localhost/EnterpriseTester/api/backgroundtasks/

Notice the use of the -X switch to change the HTTP method to POST, and the -d switch to specify a file that should be used as the contents of the request (the .json file we created). The last thing we have to do is specify the type of content we are sending to the server, by using the -H switch to set the content-type request header top be “application/json”.

The command returns almost immediately, but the re-index process will continue to execute in the background until it’s complete – notice the status code 202 Accepted, which also indicates the request is OK, but will not be immediately processed.

HTTP/1.1 202 Accepted
Date: Mon, 10 Sep 2012 21:56:46 GMT
X-AspNet-Version: 4.0.30319
Location: http://localhost/EnterpriseTester/api/backgroundtask/reindex-e21836b4-5058-49e8-b9d7-1cd0f935eb00
Cache-Control: no-cache
Pragma: no-cache
Expires: -1
Content-Type: application/json; charset=utf-8
Content-Length: 338
Connection: Close
{
  "Complete": false,
  "TotalElements": 0,
  "ProcessedElements": 0,
  "StartedAt": "2012-09-10T21:56:46Z",
  "ProgressInPercent": 0.0,
  "Id": "reindex-e21836b4-5058-49e8-b9d7-1cd0f935eb00",
  "Message": null,
  "Self": "http://localhost/EnterpriseTester/api/backgroundtask/reindex-e21836b4-5058-49e8-b9d7-1cd0f935eb00"
}

This is a quick guide to using cURL with the Enterprise Tester API. If you have any questions, feel free to give us a shout!