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.
"currentUser" : "2",
"currentRole" : "13",
"currentDivision" : "1",
"currentSystem" : "demo123",
"paging" : {"timerecords" : {
"recordCount" : "13",
"pageCount" : "2",
"page" : "1",
"pageSize" : "10",
"prevPage" : null,
"nextPage" : "https://api.actionstep.com/api/rest/timerecords?page=2"}
}
Every response will return "currentUser", "currentRole", "currentDivision", and "currentSystem" attributes. The "currentUser", "currentRole" and "currentDivision" attributes can be used to retrieve information from the Users, Roles and Divisions resources respectively.
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:
id | a unique identifier for this particular occurrence of the problem. |
---|---|
href | a URI that MAY yield further details about this particular occurrence of the problem. |
status | the HTTP status code applicable to this problem, expressed as a string value. |
code | an application-specific error code, expressed as a string value. |
title | A short, human-readable summary of the problem. This doesn't change from occurrence to occurrence of the problem, except for purposes of localization. |
detail | A human-readable explanation specific to this occurrence of the problem. |
links | Associated 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.