Requests

Endpoint

Once authorised, an endpoint unique to the cluster location of the end user's system will be returned for use in subsequent calls.

Headers

Each request MUST have the following headers:

Content-Type: application/vnd.api+json

Accept: application/vnd.api+json

Authorization: Bearer {access-token}

Methods

Each resource SHOULD support at least one method. Each resource MAY support all methods.

GET - request data for a resource(s)

POST - request to create a resource(s)

PUT - request to update a resource

DELETE - request to delete a resource(s)

OPTIONS - request what methods a resource supports

Requesting Resources

Requests for resources can be made on a single resource or a collection of resources.

return a single time record resource
GET /timerecords/1
return 3 time record resources
GET /timerecords/1,2,3 

Includes (Link Templates)

Includes are a mechanism that allow the developer to "side-load" resources related to the primary resource that is being requested. The goal of includes is to cut down on the number of requests required to collect display information and perform required operations. Some resources may utilise default includes, while most need to be specifically requested. Includes may be built using a resource's "links" attributes, which can be used individually or chained together to return deeply nested information.

The available includes are listed under each resource in the "Link Templates" section.

Examples:

include the participants resource for the timerecord.owner attribute
GET /timerecords/1?include=owner
includes the billingpreference resource for the timerecord.owner
GET /timerecords/1?include=owner.billingPreference 

Fieldsets

Fieldsets are a mechanism that allow a developer to either limit the number of resource attributes returned in a request, or inflate the number of resource attributes returned in a request. By requesting specific resource attributes a developer can return a more focused payload. This may include attributes that are not returned by default. By using the ":default" selector a developer may request all of the default attributes without having to name them individually. Similarly, the ":required" selector will return all required fields. The :default and :required selectors can be used in conjunction. Additionally, developers can request specific fields on multiple resources when an "include" is also being used. For example:

return just the billableHours and actualHours attributes for the resource
GET /timerecords/1?fields=billableHours,actualHours
return all of the default attributes for the resource, plus the createdTimestamp for the resource
GET /timerecords/1?fields=:default,createdTimestamp
return just the startTimestamp for the time records resource and just the displayName for the participants resource
GET /timerecords/1?include=owner&fields[timerecords]=startTimestamp&fields[participants]=displayName

Sorting

Sorting may be used as a parameter of the request to return resource information in a unique order. Ordering results on multiple resource attributes is possible as well as the ability to apply different sort orders on different resources, should a resource be side loaded via the include parameter. Resources are returned in Ascending order by default, but can be requested in Descending order with the use of a minus sign {-} in front of the resource attribute. For example:

return time records resource sorted by descending start times and then by ascending owners
GET /timerecords?sort=-startTimestamp,owner
return time records sorted by start time and owners sorted by their display name
GET /timerecords?include=owner&sort[timerecords]=startTimestamp&sort[participants]=displayName

Ascending or Descending?

By default the result are sorted in ASCENDING order. To change this to DESCENDING add a minus sign in front of the field name e.g. ?sort=-startTimestamp

Paging

Paging may be used as a parameter of the request to navigate through paged results of a resource. The "page" keyword is used select the desired page number. The "pageSize" keyword is used to select the size of the results returned. Each resource has a default page size and a max page size. These settings may be found defined on each resource page in the API Guide.

return page two of the time records resource
GET /timerecords?page=2
return a custom page size for the time records resource
GET /timerecords?pageSize=100

Creating Resources

The Actionstep API allows for the creation of some resources. Creation of resources may be done one or many at a time. The POST method is reserved for the creating resources.

create a new timerecord
POST /timerecords 
{
"timerecords" : {
"startTimestamp" : "2014-06-23T13:45:00+13",
"actualHours" : "12.6",
....
"links":{"action":"2960","rate:"4"}
}
}

create two new timerecords
POST /timerecords
{
"timerecords" : [{
"startTimestamp" : "2014-06-23T13:45:00+13",
"actualHours" : "12.6",
....
"links":{"action":"2960","rate:"4"}
}, {
"startTimestamp" : "2014-08-01T11:23:00+13",
"actualHours" : "2.8",
...
}]
}

Linked Resources

If you want to create or update a "linked" resource (for example specifying an action id or rate id when posting a time record) add these fields in a "links":{} section of the JSON payload.

Updating Resources

The Actionstep API allows for the updating of some resources. Updating of resources may be done one or many at a time. The PUT method is reserved for the updating of resources.

update timerecords 1
PUT /timerecords/1 
{
"timerecords" : {
"id" : "1",
"actualHours" : "2.6"
}
}

update timerecords 1 and 2
PUT /timerecords/1,2
{
"timerecords" : [{
"id" : "1",
"actualHours" : "2.6"
}, {
"id" : "2",
"actualHours" : "2.2"
}]
}

Deleting Resources

The Actionstep API allows for the deleting of some resources. Deleting of resources may be done one or many at a time. The DELETE method is reserved for the deleting of resources. When a resource is deleted the API server will respond with a 204 No Content status code if successful.

delete timerecords 1
DELETE /timerecords/1
delete timerecords 1 and 2
DELETE /timerecords/1,2

Uploading Files

Uploading files with the Actionstep API is a multiple-step process. First you must upload the document using the Files resource in 5mb (5242880 bytes) chunks (or in 1 chunk if <= 5mb). This will give you an identifier which you can then use in a regular PUT/POST request for any field which is of type "file".

Upload a document (hello-world.pdf) which is exactly 6mb in size:
POST /files?part_count=2&part_number=1
Content-Length: 5242880
Content-Type: multipart/form-data; boundary=---------------somerandomstring1233243324

---------------somerandomstring1233243324
Content-Disposition: form-data; name="file"; filename="hello-world.pdf"
Content-Type: application/octet-stream

{first 5mb of binary data goes here!}
---------------somerandomstring1233243324--
Response:
{"files":{"id":"YmEzYzlmOWFjMDYwMTA1NzdkZTE5YzM2NjIzMjI5NzRhOWNmMGQzMzIyY2Uz","status":"Pending"}}

Second Request:
POST /files/YmEzYzlmOWFjMDYwMTA1NzdkZTE5YzM2NjIzMjI5NzRhOWNmMGQzMzIyY2Uz?part_count=2&part_number=2
Content-Length: 1048576
Content-Type: multipart/form-data; boundary=---------------somerandomstring1233243324

---------------somerandomstring1233243324
Content-Disposition: form-data; name="file"; filename="hello-world.pdf"
Content-Type: application/octet-stream

{last 1mb of binary data goes here!}
---------------somerandomstring1233243324--
Response:
{"files":{"id":"YmEzYzlmOWFjMDYwMTA1NzdkZTE5YzM2NjIzMjI5NzRhOWNmMGQzMzIyY2Uz","status":"Uploaded"}}

Create an email attachment with the uploaded file
Note the file-identifier also includes the file-name we want to rename the upload the file as. This is required.

POST /api/rest/emailattachments
{
"emailattachments" : {
  "contentDisposition" : "attachment",
  "displayName" : "hello-world.pdf",
  "fileIdentifier" : "YmEzYzlmOWFjMDYwMTA1NzdkZTE5YzM2NjIzMjI5NzRhOWNmMGQzMzIyY2Uz;hello-world.pdf",
  "links" : {
   "email" : "1400"
  }
}
}