• Using cURL

• Update Multiple Parameters

• Update Multiple Parameters with JSON

• Create a new project

• Analyze the POST response

• Read information about your new project

• Analyze the GET response

• Update the information in your new project

• Analyze the PUT response

• Delete your new project

• Analyze the DELETE response

• Print your JSON response

• Return to Navigation

Using cURL to update objects

Postman is a good tool for organizing your requests and responses, and it's one of many GUI programs that are used by API programmers. Another industry standard tool that is used throughout industry is called cURL. This tool is a UI, but unlike Postman, it isn't a graphic UI. The reason why cURL is so widely used is because it is a command line tool which was built to interface with many different protocols, including HTTP. The versitility of cURL and command line access make it a powerful and relatively simple platform to interface your APIs with.

On most iOS machines, and most new Windows machines, cURL comes installed as a factory default. To check if your machine already has cURL installed, you can open your Mac Terminal, or Windows Command Prompt and type:

The following is a response from a Windows machine, but the response on a iOS machine should be mostly similar, with iOS references substituted for the Windows references:

If you received a response that is not similar to the one above, you do not have cURL installed on your machine. To obtain cURL free from its offical release site visit: cURL.haxx.se.

To begin, obtain an apiKey from the instance of Workfront that you are using. This key will be used to authenticate the requests that you pass through cURL.

To start, here is an example of a basic login request:

This may look similar to a requests that you've made using Postman, but there are some differences. Notice that to begin a cURL request in the command line, you prepend "curl" to the begining of your request. The next part of the request "-X POST" specifies the method of your request. If nothing is specified for the method, cURL will typically default to making a GET request. Following the method is the URI where you are sending your request to.

The next two parts, preceded by the "-d" are known as "options" in cURL. The "-d" option is telling the API that you are passing data that needs to be evaluated. In this case, a "username" and "password". Currently, cURL has over 200 different options. A list of these options can be found on their official documentation page. Or, you can access them directly through cURL by submitting the requests: "curl -h" or "curl --manual".

Here is what the return for that request should look like:

Notice that this can be reformatted with line breaks for easier reading:

Using the apiKey that was generated for your instance of Workfront, or the sessionID that was returned with your login, create a project using the following:

You can now receive information about that project by requesting:

Notice that this request returns the same information that was returned by the system when you created it.

Update using multiple parameters at once

If you would like to update more than one property of this project at a time, you can use cURL to send additional headers, in a manner similar to what was demonstrated above.

This method is fine if you only need to make a small number of updates, to a small number of properties, on a small number of objects. However, in such cases, it might actually be easier to use the Workfront UI instead of parsing through code. Ideally, you should be using the Workfront API to simplify processes that are not easy to carry out via the Workfront UI, or to create features which do not exist in the UI.

Update multiple parameters using a JSON document

One way to speed up the efficiency of making API requests is to create a JSON file which can be used to update multiple objects and properties at the same time.

This simplified example demonstrates the process of updating multiple properties on the new project that you just created:

1. Start by opening a plain-text document.
2. Copy the contents of the response that you received when making the last GET request about your project.
3. Reformat this content so that it looks like the following:
{
"ID":"5d7abf161240f2b514613bdc80358f8a",
"name":"NewProject",
"objCode":"PROJ",
"percentComplete":0.0,
"plannedCompletionDate":"2019-09-15T06:00:00:000-0600",
"plannedStartDate":"2019-09-15T06:00:00:000-0600",
"priority":0,
"projectedCompletionDate":"2019-09-15T06:00:00:000-0600",
"status":"PLN"
}

4. Save the document with a file name that you can easily recall using the extension: .JSON. Make sure that you save the document in a location that you can locate easily--this is important.
5. Don't close the document after you save it.
6. Using Terminal, or your command prompt, navigate to the folder where you saved your JSON file. In this case, the file's name is "curlTest.JSON" and it is located in the directory "C:\cURL". This is an example of how to navigate to the directory "cURL" from the "C:\" drive and view its contents using the "dir" command:
C:\>
C:\>cd curl
C:\cURL> dir
Directory of C:\cURL
curlTest.JSON
1 File(s) 413 bytes

C:\cURL>

7. Inside the JSON document, edit the fields that you wish to update.

Depending on your default project settings, not all fields will be immediately available for update. Endpoints like percentComplete may require you to pass additional information with your request, or change the settings of your project.

{
"ID": "5d7abf161240f2b514613bdc80358f8a",
"name": "LatestName",
"objCode": "PROJ",
"percentComplete": 0.0,
"plannedCompletionDate": "2019-09-15T06:00:00:000-0600",
"plannedStartDate": "2019-09-15T06:00:00:000-0600",
"priority": 4,
"projectedCompletionDate": "2019-09-15T06:00:00:000-0600",
"status": "CUR"
}

8. After updating your document, save it and close it.
9. Use the following cURL command to send your document to the Workfront API and update your project:
curl -X PUT "https://workfrontdocs.workfront.com/attask/api/v9.0/proj/5d7abf161240f2b514613bdc80358f8a" -d @curlTest.json -H "Content-Type: application/json" -H "Accept: application/json" -H "apiKey: f69o2acf6idpow3hlc3btmrgbtdjalk2"

Notice that the data heading is returned with the response, but will not be accepted if it is sent with a request.

There are many different ways that you can interact with the Workfront API. Using cURL is one way to simplify the process of updating or viewing multiple objects by using JSON documents.