Responses
- Jeremy Bruce (Unlicensed)
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:
| 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.