Code42 API syntax and usage
Overview
The Code42 API is a powerful tool for gaining specific insights or performing programmatic actions on all parts of your Code42 environment. This article describes the syntax of the Code42 API and how to use it.
The examples in this article use the command line tool curl to interact with the Code42 API. For a list of tools that can be used to interact with the API, see Code42 API Tools.
Code42 API syntax
The Code42 API is an HTTP API that is made up of resources that you can interact with using methods and parameters.
The following example request shows how these components can be used to interact with the Code42 API:
Resources
Code42 API resources provide interfaces to various components of the Code42 platform. For example:
- The
Computerresource provides access to client devices in your Code42 environment. - The
Orgresource provides access to the organizations in your Code42 environment. - The
Userresource provides access to the users in your Code42 environment.
To view a complete list of Code42 API resources, use the API Documentation Viewer.
Methods
Methods allow you to interact with resources. The API Documentation Viewer displays the methods that are available for each resource.
| Method | Description |
|---|---|
| GET | Retrieve a resource. |
| POST | Create a new resource. |
| PUT | Update an existing resource. |
| DELETE | Destroy an existing resource. |
Parameters
Parameters allow you to fine tune the action taken by the method. The API Documentation Viewer displays the query parameters that are valid for each method.
Get parameters
GET requests allow an HTTP query string, such as ?x=y, or an ID as part of the main URL to specify which instances should be returned.
HTTP query string example
curl -X GET -u 'username:password' 'https://www.crashplan.com/api/User?q=joe@acme.com&active=true'
ID example
curl -X GET -u 'username:password' 'https://www.crashplan.com/api/User/123?idType=uid'
Post and put parameters
POST and PUT requests do not accept a query string, but receive data in the body encoded as JSON. Specify a Content-Type of application/json.
curl -X POST -u 'username:password' -d '{ "company": "Test1", "email": "test@test.com", "customerId" : "123", "firstname": "test", "lastname": "test" }' -H 'Content-Type: application/json' 'https://www.crashplan.com/api/user'
Return values
Return values are formatted in JavaScript Object Notation (JSON).
- Return values can be one resource or an array of resources.
- To make the output more readable, we recommend piping it to the Python json decoder. To do so, add the following to the
curlcommand:| python -m json.tool
Single return values
GET requests that have an ID specified on the main URL return one resource. For example:
curl -X GET -i -u 'username:password' 'https://www.crashplan.com/api/User/123' | python -m json.tool
The user with ID "123" is returned:
{
"metadata":{
"timestamp":"2013-08-27T14:05:44.733-05:00",<
"params":{
}
},
"data":{
"userId":123,
"userUid":"c6ec2d26ce3805c1",
"status":"Active",
"username":"joe@acme.com",
"email":"joe@acme.com",
"firstName":"Joe",
"lastName":"Jones",
"orgId":42,
"orgName":"CrashPlan",
"active":true,
"blocked":false,
"orgType":"CONSUMER",
"creationDate":"2007-01-07T18:00:13.273-06:00",
"modificationDate":"2013-05-13T13:40:52.279-05:00"
}
}
Note that POST requests usually return the resource that was created with the generated ID for convenience.
Multiple return values
GET requests with query parameters return an array of resources. For example:
curl -X GET -u 'username:password' 'https://www.crashplan.com/api/User?active=true&pgNum=1&pgSize=2' | python -m json.tool
An array of active users is returned:
{
"metadata":{
"timestamp":"2013-08-27T14:05:44.733-05:00",
"params":{
}
},
"data": {
totalCount:5432,
users: [
{
"userId":123,
"userUid":"c6ec2d26ce3805c1",
"status":"Active",
"username":"joe@acme.com",
"email":"joe@acme.com",
... [snipped]
},
{
"userId":456,
"userUid":"f1ad1da8b74328bz",
"status":"Active",
"username":"jim@slim.com",
"email":"jim@slim.com",
... [snipped]
},
]
}
}
Example interactions with the computer resource
The example in this section uses curl to interact with the Computer API resource.
Input
The following command lists the devices in your Code42 environment:
curl -X GET -k -u 'user:pass' "https://master-server.example.com:4285/api/Computer" | python -m json.tool
| Command Element | Description |
|---|---|
curl |
Invokes the curl command. |
-X GET |
Sets the method to GET. |
-k |
Ignores security errors related to self-signed certificates on a master server. Refer to curl's man page for details. |
-u 'user:pass' |
Includes a username and password for your API request.
|
https://master-server.example.com:4285 |
The website protocol, host, and port of your master server. |
/api |
The network location of API resources on your master server, required for all API requests. |
/Computer |
The specific API resource you wish to use. A full list of API resources is available in the API Documentation Viewer on your master server. |
| python -m json.tool |
Makes the output more readable by sending it to the Python json decoder. |
Be aware that this method of interacting with the Code42 API can expose your credentials on your device and your network. For more secure authentication options, see the curl documentation, or consider using a different API tool with additional security options.
Output
The output contains the requested information as formatted by the Python json.tool:
{
"data": {
"computers": [
{
"active": false,
"address": "192.168.95.128:4242",
"alertState": 0,
"alertStates": [
"OK"
],
"blocked": false,
"buildVersion": null,
"computerId": 13,
"creationDate": "2015-03-18T16:39:04.241-05:00",
"guid": "681099810721783680",
"javaVersion": "1.7.0_45",
"lastConnected": "2015-03-18T16:42:55.482-05:00",
"loginDate": "2015-03-18T16:39:07.570-05:00",
"modelInfo": null,
"modificationDate": "2015-03-18T16:42:55.482-05:00",
"name": "WIN-FQNN6BGK47K",
"orgId": 2,
"osArch": "amd64",
"osName": "win",
"osVersion": "6.2",
"parentComputerId": null,
"productVersion": "3.7.0",
"remoteAddress": "172.16.239.1",
"service": "CrashPlan",
"status": "Deactivated",
"timeZone": "America/Chicago",
"type": "COMPUTER",
"userId": 2,
"version": 1388728800370
},
{
"active": true,
"address": "192.168.95.128:4252",
"alertState": 0,
"alertStates": [
"OK"
],
"blocked": false,
"buildVersion": 31,
"computerId": 12,
"creationDate": "2015-03-12T11:53:40.861-05:00",
"guid": "680201360538886016",
"javaVersion": null,
"lastConnected": "2015-03-12T17:17:23.909-05:00",
"loginDate": "2015-03-12T16:23:12.272-05:00",
"modelInfo": null,
"modificationDate": "2015-03-12T17:17:23.909-05:00",
"name": "WIN-FQNN6BGK47K",
"orgId": 2,
"osArch": null,
"osName": "win",
"osVersion": "6.2.9200.0",
"parentComputerId": null,
"productVersion": "3.7.0",
"remoteAddress": "172.16.239.1",
"service": "CrashPlan",
"status": "Active",
"timeZone": null,
"type": "COMPUTER",
"userId": 2,
"version": 1413349200416
}
]
},
"metadata": {
"params": {},
"timestamp": "2015-03-23T16:57:19.687-05:00"
}
}
Adding parameters as described below can improve on this initial request.
Add parameters
Each API resource includes additional parameters, which can be used to search for specific data, filter and sort results, or specify other additional options. The parameters are not the same for each resource, so use the API documentation viewer to review the available options for each resource you use.
To improve on the Computer request above, add parameters and specify values to tailor your results. The examples included below are only a few of the parameters available in the Computer resource.
| Example Parameter | API Documentation | Description |
|---|---|---|
srtKey |
key to sort on | Sorts the results of the Computer request by one of several values, such as the computer's name or lastCompletedBackup. |
srtDir |
direction of sort | Sorts results in ascending or descending order. |
pgSize |
the max number of objects to return | Specifies a maximum number of results. |
active |
optional filter to show only active or deactivated objects | Allows the request to respond with only active or deactivated computers. |
export |
option to specify an export | Instructs the Computer request to return results in an exported format, such as a comma-separated values (CSV) file. |
You can attach parameters to a curl request by adding one or more parameters and their values after a ? as shown below.
Example 1: Sort by recent connections
If you want to see which computers have most recently connected to your Code42 environment, you can sort the results of a Computer API request. This command sorts the Computer results by the last connection of the computer to a Code42 server:
curl -X GET -k -u 'user:pass' "https://master-server.example.com:4285/api/Computer?srtKey=lastConnected" | python -m json.tool
Example 2: Export to CSV
If you want to see a more readable information format, or store reports to review information on your Code42 environment over time, you can export the data of a Computer request to a CSV file. This command exports its results in a CSV format:
curl -X GET -k -u 'user:pass' "https://master-server.example.com:4285/api/Computer?export=csv" | python -m json.tool
Example 3: Sort and export to CSV
Combine multiple parameters in a single curl command by using the & character. This command sorts the Computer results by the last connection and exports the results in a CSV format:
curl -X GET -k -u 'user:pass' "https://master-server.example.com:4285/api/Computer?srtKey=lastConnected&export=csv" | python -m json.tool
Use cases for the computer resource
By combining the available resources, methods, and parameters of the Code42 API, you can create solutions for the specific needs of your Code42 environment. These examples show solutions that use only the Computer resource.
Report all devices
The Code42 API can help you regularly gather information on your Code42 environment for later use in reporting and statistics. This request exports a list of all your devices as a CSV:
curl -X GET -k -u 'user:pass' "https://master-server.example.com:4285/console/api/Computer?srtKey=name&srtDir=asc&targetComputerGuid=rollup&incBackupUsage=true&incActivity=true&incCounts=true&active=true&alerted=false&obeyQueryLimit=true&export=csv" | python -m json.tool
In fact, this curl command uses the same API request that the administration console uses when you select Devices > action menu > Export All. For information about how to convert administration console actions into curl commands, see our Code42 API Tools article.
Identify inactive devices
You may have devices in your Code42 environment that have not connected to your Code42 servers in some time, perhaps due to simply being powered down. This request creates a CSV of the computers in your Code42 environment beginning with those that have not connected to your Code42 environment in the longest time:
curl -X GET -k -u 'user:pass' "https://master-server.example.com:4285/api/Computer?srtKey=lastConnected&active=true&export=csv" | python -m json.tool
Identify largest device backups
Identifying the devices that are backing up the most information can help you more effectively manage your storage. This request lists the ten devices that are backing up the most data:
curl -X GET -k -u 'admin:admin' "https://master-server.example.com:4285/api/Computer?srtKey=archiveBytes&srtDir=DESC&pgSize=10&pagNum=1&active=true" | python -m json.tool
To make this command more easily readable on a command line, process the output with the Python JSON decoder and filter the results to show only the device name using a command-line tool like grep:
curl -X GET -k -u 'admin:admin' "https://master-server.example.com:4285/api/Computer?srtKey=archiveBytes&srtDir=DESC&pgSize=10&pagNum=1&active=true" | python -m json.tool | grep -w name
What's next
The Computer resource is just one of many resources in the Code42 API. After you understand the examples in this introduction, continue exploring the Code42 API:
- Examine the API Documentation Viewer to learn about the other resources available.
- Read our introduction to the Code42 examples on Github.
- Check our GitHub repository for information and scripts that we publish for use in any Code42 environment.