Responses

Request responses to the Actionstep API will all return content in a consistent manner. Response MAY return with only Header content while others MAY also return content in the Body of the response.

GET Response

The Content-Type Header will always be: application/vnd.api+json

Each response that return Body content will have the following top-level objects: links, data, linked, and meta  

If an error occurs while processing the request the only top-level object that will be return is: errors

Links

The links object is a collection of URL templates to be used to expand the primary resource's related resources. Each resource document in the API guide has a list of URL templates that will be included in the response. Below is a representation of how the links object may look like in the a response.

"links" : {

"timerecords.owner" : {

"href" : "https://api.actionstep.com/api/rest/participants/{timerecords.owner},
"type" : "participants"

}

}

Data

The term "data" is an alias for the name of the request resource. For example, if a call was made to retrieve data on a timerecords resource, then the name of the returned "data" object would be "timerecords".  Below is a representation of what the data object may look like in the response for a collection of timerecords resources.

"timerecords" : [{

"id" : "533",
"startTimestamp" : "2014-07-23T15:09:46+12:00",
"notes" : null,
"actualHours" : "1.00",
"billableHours" : "1.00",
"links" : {

"owner" : "120"

}

} , {

"id" : "539",
"startTimestamp" : "2014-07-30T13:21:19+12:00",
"notes" : null,
 "actualHours" : "0.17",
"billableHours" : "10.00",
"links"  : {

"owner" : "14"

}

}]

Every resource return in the "data" object will include an "id" attribute which is the unique identifier for that resource object. Resource objects may also have a "links" attribute which catalogue the "ids" of related resources for which the top-level "links" object details URL templates for those resources.

Linked

The linked object is a collection of resource objects, grouped by type, that are linked to the primary resource and/or to each other. These objects appear in the response as defaults set by the primary resource or specifically requested using the "include" parameter. Below is a representation of what the linked object may look like in a response.

"linked" : {

"participants" : [{

"id" : "14",
"displayName" : "Aaron Rodriguez",
"email" : "aaron@email.com",
"isCompany" : false,
"links" : {

"country" : "US"

}

}, {

"id" : "120",
"displayName" : "Bob Smith",
"email" : "bob@email.com",
"isCompany" : false,
 "links"  : {

"country" : "NZ"

}

}]

Meta

The meta object is reserved for meta-information that may be returned with the response. Information such are paging is returned in the meta object when applicable. Below is a representation of what the linked object may look like in a response.

"paging" : {

"timerecords" : {

"recordCount" : "13",
"pageCount" : "2",
"page" : "1",
"pageSize" : "10",
"prevPage" : null,
"nextPage" : "https://api.actionstep.com/api/rest/timerecords?page=2" 

}

}

POST Response

When successfully creating resource(s) a 201 Created response will be given and the response will return the resource as though it had been requested with the GET method.


PUT Response

When successfully updating resource(s) a 200 OK response will be given and the response will return the resource as though it had been requested with the GET method.


DELETE Response

When a resource(s) is deleted a 204 No Content response will be given.


OPTIONS Response

When the OPTIONS method is called on a resource a HTML document is returned describing the resource properties and the methods that are available to it.  


ERROR Response

When an error occurs while processes a request, a response is returned with the errors object as the sole top-level object. Error objects MAY have the following attributes:

ida unique identifier for this particular occurrence of the problem.
hrefa URI that MAY yield further details about this particular occurrence of the problem.
statusthe HTTP status code applicable to this problem, expressed as a string value.
codean application-specific error code, expressed as a string value.
titleA short, human-readable summary of the problem. This doesn't change from occurrence to occurrence of the problem, except for purposes of localization.
detailA human-readable explanation specific to this occurrence of the problem.
linksAssociated resources which can be dereferenced from the request document.
path

The relative path to the relevant attribute within the associated resource(s). Will only exist for problems that apply to a single resource or type of resource.

* Other error attributes MAY be included in the response if required.