Api wiki · git hub

Clone this wiki locally
Home
Sean McKenna edited this page on 20 Oct 2016 · 7 revisions
TrackAbout API Documentation
This is our in-depth documentation, for an overview of API endpoints please see our Interactive API
Reference.
Table of Contents
Introduction and Setup
Getting Started1.
HTTP vs HTTPS2.
User Agent3.
Security and Data Integrity4.
Understanding the API
REST Concepts5.
Interactive Documentation6.
Formats and Encoding7.
Basic Data Types8.
Validation9.
Implementation
Authentication9.
Standard Request/Response Patterns10.
Batch Requests11.
Status Codes and Errors12.
Sample Requests13.
Getting Started
The TrackAbout API provides a REST interface for sending data to TrackAbout, retrieving data, and
recording user activity (creating records). This documentation includes requirements for using the
API, descriptions of API formats and patterns, and guides and examples for common API
interactions.
New API clients will need a TrackAbout test environment, a user account, and an API key. Contact
TrackAbout support if you have any questions about this. Please read this entire document
thoroughly before starting implementation.
HTTP vs. HTTPS
All requests must be made using https . The TrackAbout API will not respond to requests made
using an http URL.
User-Agent
trackabout / API
Home
Tools for .NET Clients
Personal Open source Business Explore Pricing Sign in or Sign up
16 1 0
Code Issues 0 Pull requests 0 Projects 0 Wiki Pulse Graphs
Pages 2
Clone in Desktop
Watch Star Fork
Home · trackabout/API Wiki · GitHub https://github.com/trackabout/API/wiki#getting-started
1 of 13 20/02/2017 10:24

All API clients should send a User-Agent HTTP header to identify the software and/or device
making the request. TrackAbout may log the User Agent header and use it for metrics and support
requests. This header will be required unless special arrangements are made with TrackAbout.
Ideally, the header value should include a list of product tokens that identify the client application,
listed in order of importance. For example:
Client application name and version1.
Operating system name and version2.
Device name and version, if the application is running on a mobile device or other non-PC
hardware
3.
Each product token should be the the name of the software or hardware, followed optionally by a
slash and the version or build number. Tokens are separated by spaces, and there should be no
spaces within individual tokens. It's also possible to provide comments between parentheses if
needed.
Here are some examples of well-formed User Agent strings:
MyMobileApp/1.2.3 iOS/6.1 iPhone/4
MyEnterpriseMiddleware/Build-1234 (For TrackAbout release AWS0123; 2013-07-23) ERPSystemX Solaris/11.1
For those interested, RFC 2616 provides detailed specifications for the recommended syntax of
User Agent strings.
Security
As mentioned above, all requests must be made using HTTPS. Therefore all requests are safely
encrypted using SSL.
Data Integrity
All requests made are safely wrapped in database transactions. Meaning if there is an
unrecoverable error, for example if the connection was dropped, during the request and/or
processing, the database will safely rollback any data changes to avoid inconsistent/invalid data.
REST Concepts
Request Methods
REST APIs use standard HTTP methods to describe the type of action to take against the resource
identified in the request URI. As such, the TrackAbout API follows the standard semantics of these
HTTP methods:
GET is for retrieving data without modifying the state of the system
POST is for creating new resources, or for other general operations that have significant side
effects
PUT is for updating the state of an existing resource. The body of the request is intended to
fully describe the intended state of the resource
PATCH allows for partially updating a resource. In a typical patch request, all of the fields in the
request body are optional. Only the fields included in a specfic request are updated, and other
properties of the resource remain unchanged. Where allowed, sending a field with an empty
string or array value will clear the value of that property in TrackAbout
Idempotency
An idempotent request can be re-sent any number of times and have the same effect. For example,
a GET request repeated with the same URL and parameters will retrieve the same data (assuming
the underlying state of the data does not change), and a PUT or PATCH request repeated with the
same URL and body will result in the identified resource having the same state.
POST requests are defined as being non-idempotent. A simple example is a request for creating a
new resource; repeated POST requests will create multiple instances of resources with different
2 of 13 20/02/2017 10:24

unique IDs, or repeated requests may fail due to uniqueness requirements. In the TrackAbout API,
some other requests are defined as POST because of significant side effects, such as creating
records or modifying asset history.
Interactive Documentation
The TrackAbout API offers an interactive documentation page. Anonymous access is available, but
to enable interactive features you will first need to log in to TrackAbout using your TrackAbout
credentials.
The documentation describes each API operation, sorted by URI. For each operation, you can view:
The URI and method ( GET , POST , etc.) of the operation
A description of the operation
The structure of the request body (if applicable) and response body (click the Model Schema
links to view sample JSON)
Descriptions of URL parameters
Note that the base URL for every API operation is /api ; ensure that all of the URLs you form in
your web service client have this base path.
The documentation is interactive in that you can send test requests to most endpoints from within
your web browser. If the request takes URL parameters or requires data posted in the request
body, enter appropriate values into the text boxes for each parameter. For requests that require
data in the request body (e.g. most POST requests), you can click the Model Schema link in the
request body description to see a JSON sample, and you can click on the JSON sample itself to
copy it to the text box as a template for the request body you will send. Once you’ve entered the
necessary values, click the Send Request button to send the request and view the response headers
and body.
Note that the interactive documentation automatically uses your TrackAbout web site session to
authenticate your test requests. To construct requests programatically, you will need to add
authentication headers as described below. Furthermore, the requests being sent are both
validated and processed by the server. Sending non-GET requests will result in created and/or
modified data.
Formats and Encoding
The TrackAbout API only supports JSON for requests and responses at this time. All requests
should either have the request header Accept: application/json , or have format=json as a query
string parameter. When sending data in the request body for a POST or PUT request, send the data
in JSON format and add the request header Content-type: application/json .
The Sample Requests at the end of this document show examples of correct usage of request
headers.
UTF-8 Encoding
Every string passed to and from the TrackAbout API needs to be UTF-8 encoded.
Response Compression
The TrackAbout API supports compression for most responses. To request a compressed response,
include the Accept-Encoding header. The API supports gzip and deflate encoding schemas. For
example:
Accept-Encoding: gzip,deflate
Request Compression
The API also has limited support for compressed request body content in POST/PUT/PATCH
requests. Only the gzip encoding schema is supported. Compress the entire content of the
request body and include the header Content-Encoding: gzip in the request.
3 of 13 20/02/2017 10:24

Basic Data Types
The following table describes each of the basic data types used by the API and how they are
identified by the interactive documentation:
Data Type JSON Format/Range
byte 0–255 (unsigned)
boolean 1 / 0 / true / false
int 32-bit integers
long 64-bit integers
float 32-bit floating point
double 64-bit floating point
string "value"
Date yyyy-mm-ddThh:mm:ssZ
Array [value1, value2, ...]
Date Format
The recommended format for date/time values is ISO 8601 combined date and time format. Unless
otherwise specified, all date fields should include both a date and time value. Time values should
be sent in UTC using the "Z" or "+00:00" time zone designator. Requests sent in without a
timezone specified will be rejected with a 400 Bad Request .
Date-only fields will provide a format string to indicate how they should be strucutured. They will
be interpreted with the headquarters' timezone.
Here is an example of an acceptable date value for TrackAbout API requests and responses:
2013-06-21T09:41:08Z
String Value Restrictions (Enumerated Values)
Some string values in the API represent enumerated types: they are restricted to a set of known
values. The interactive documentation will list the allowed values when possible. For example, the
orderType field in some of the Orders endpoints is documented like this:
orderType (string) = ['CustomerDelivery' or 'BranchTransfer']
The request JSON should look like this:
{ "orderType": "CustomerDelivery", ... }
If you send value that is not one of the accepted values, the request will fail with status code 400.
Validation
Most APIs perform basic validation before the request is processed and will return a 400 error code
if any validation fails. The response body will contain information as to what field or fields failed
and why. For an example, see the 400 status code in the status code section below.
When working with an API for the first time, you can browse the associated validation and required
fields directly by going to the validation documentation. This avoids having to send a "dummy"
request to the API and receive the validation errors.
Authentication
The TrackAbout API supports Basic Authentication and Token Authentication. Each request must
4 of 13 20/02/2017 10:24

include valid HTTP headers that identify the user with one of these authentication methods. Basic
Authentication is appropriate for batch requests or other low volume activity from automated
systems; for example, synchronizing order data with a client accounting system. Token
Authentication is appropriate for high volume requests or applications in which a human user
athenticates using TrackAbout credentials.
Basic Authentication
A special web services user account should be used for basic authentication. You will also need a
TrackAbout API Key. Ask TrackAbout Support for help setting these up.
Each request must include two HTTP headers: X-API-Key and an Authorization header. Use the
former header to provide the TrackAbout API Key with every request:
X-API-Key: 950384A9-12DB-43B8-A8BB-DC8095CE2A3A
The value of the Authorization header consists of a valid username and password, concatenated
with a colon, like this:
user1:password1
This combination should then be base64 encoded, resulting in something like:
dXNlcjE6cGFzc3dvcmQx
An example of a request with the necessary Basic Authentication headers would thus be:
GET https://test.trackabout.com/api/locations HTTP/1.1
Host: test.trackabout.com
Authorization: Basic dXNlcjE6cGFzc3dvcmQx
Accept: application/json
Token Authentication
With Token Authentication, the client sends a single request to the tokens API endpoint, which
validates a human user's credentials and returns a unique token that can be used for identifying
future API requests without resending the password. For Token Authentication, you will need a
TrackAbout API Key. Ask TrackAbout Support for help setting this up.
To generate and retrieve a token:
POST https://test.trackabout.com/api/tokens/basic HTTP/1.1
Content-type: application/json
{
"username": "user1",
"password": "password1",
"apiKey": "AC967D07-327D-410E-A579-C856CAC2A8EA",
"applicationInstanceId": "12345ABCDE"
}
The apiKey is provided by TrackAbout, and identifies your client application. The
applicationInstanceId value is generated by the client and is meant to uniquely indentify a
specific installation of the client application on a particular machine or device. For example, if this is
a mobile app deployed to a rugged device or smartphone, the same API key would be used for all
instances of the app, and the applicationInstanceId should be unique for each device it is
installed on. If it's a console application running on a server, a single ID value is sufficient.
If the username and password identify a valid user, the response would look like this:
{
5 of 13 20/02/2017 10:24

"token": "VGhpcyBpcyBhIHNhbXBsZSB0b2tlbiBzdHJpbmcu",
"expires": "2013-08-07T20:45:32.8892477Z"
}
The token value should be used in all subsequent requests to the API to identify this
authenticated user, using the X-Token HTTP header. For example:
GET /api/locations HTTP/1.1
X-Token: VGhpcyBpcyBhIHNhbXBsZSB0b2tlbiBzdHJpbmcu
This token can be reused, as long as it's not expired, for the length of time that the given user is
logged in. Tokens should not be reused over mulitple applicationInstanceIds . The X-API-Key
header is not required when using token authentication because the API Key is embedded in the
token value.
Impersonating a User
For requests that create records in TrackAbout, such as a load truck action, you can authenticate as
one user (typically a shared web service user) and create the record using the identity of a different
user (the human user actually performing the business activity). Specify the user to impersonate
with the X-Impersonate-User header, in addition to supplying the primary credentials as described
above. There are multiple ways to identify the user to impersonate, as determined by a second
header X-Impersonation-Method .
To identify a user by TrackAbout username:
X-Impersonate-User: username1
X-Impersonation-Method: Username
To identify by Accounting User ID (an identifier that can be registered in TrackAbout to match a
user’s identity as stored in an external system):
X-Impersonate-User: accountingSystemIDabc
X-Impersonation-Method: AccountingUserId
To use this feature, the API endpoint must support impersonation, and the user with which you are
authenticating must have the correct permissions assigned in TrackAbout. If you receive a 403
Forbidden error response, the error message may indicate that the endpoint does not support
impersonation or that your API user does not have permission to perform impersonation. Please
contact TrackAbout Support to resolve permissions issues.
Standard Patterns
The TrackAbout API makes use of a few standard patterns you will find across multiple endpoints.
Response Envelope
Many requests will return a list of items. The list is wrapped in a response object with a total-rows
field, as seen below. This is useful when you are working with paging functionality and the
response is a subset of the total result set.
Sample response from truck endpoint. Notice that there are 50 total rows but only 3 are currently
returned:
{
"totalRows": 50,
"rows": [{
"tId": 456,
"name": "Little Red Truck"
}, {
"tId": 123,
"name": "New Truck 1"
6 of 13 20/02/2017 10:24

}, {
"tId": 789,
}
]
}
TId and MId
Many resources in the TrackAbout Api can be identified with multiple IDs depending upon who
"owns" the data. To avoid ambiguity in these cases, TId and MId are used. The TId ("TrackAbout
ID") represents the ID that TrackAbout uses internally for the resource. The MId ("Master Id")
represents the ID that the accounting or backend system uses for the resource. When identifying a
resource in a request body, the resource will often be represented as an object with both types of
identifiers. Only one is required, and if both are supplied, the TId is preferred. For example, the
customer and originLocation resources are identified in two different ways in this POST request:
{
"orderNumber": "ORDER123",
"customer": { "tId": 85 },
"originLocation": { "mId": "Location456" },
...
}
Reference Objects
When a response contains information about an object that has its own API endpoint, only minimal
information will be returned about this referenced object. This is to keep performance high and to
encourage making a second request for that object's data instead of returning everything in one
large "data dump". The standard design of these reference objects is to return the tId , name , and
mId for the object. This tId is provided to allow querying of the resource directly and the name
and mId are provided for context.
Below is an example of the response from the assets endpoint for an individual asset. Notice how
only the tId , name , and mId are returned for the referenced customer object.
{
"rows": [
{
"customAssetProperties": [],
"customer": {
"tId": 12269,
"name": "John Doe",
"mId": "Doe"
},
"tId": 123,
"tag": "456"
}
],
"totalRows": 1
}
Paging
Requests that have the potential for a large number of results support paging. Requests that
support paging note this in their associated documentation on the docs page. There are 3 query
string parameters that control the result set.
Paging determines whether or not paging is enabled. This must be set to true to use the
other options. The default setting is true because non-paged results can take a much longer
time to run and can create very large responses.
Page determines the specific page of data that the request would like. Page 1 indicates the
first page.
PageSize determines the number of rows to return per page. The default is 50. Note that
requesting larger page sizes can negatively impact the performance and greatly increase the
response size.
7 of 13 20/02/2017 10:24

Record-Saving APIs
A variety of POST endpoints are designed for creating records (in other words, saving actions) in
TrackAbout. These APIs have a number of common elements:
Dates: the userEntryEndDate is the effective date of the record, typically the date/time at
which the user finished the action. userEntryStartDate is the start date of the record, the
date/time at which the user began
Assets: most record saving APIs require one or more assets or hard goods. Unique assets
typically have fields for tag and serialNumber , usually only one is required. An asset's
timeEntered is the date/time at which the asset was scanned or recorded for the action.
Assets may have additional fields as relevant to the specific type of record
Dynamic Forms: to utilize TrackAbout's Dynamic Forms feature, use the dynamicFormEntries
field. Each element in the array represents the value of a single form field entered by the user.
Consult TrackAbout support for assistance with this feature.
Custom Properties
Custom Properties are name-value pairs describing additional client-specific information for a
resource. In some GET requests, custom properties can be requested by listing the TIds of the
custom properties in a query string parameter. The response will include a list of the names, TIds,
and values for each requested custom property that is defined for the given resource.
To determine the list of custom property types available, there are various API endpoints with
paths ending in names such as customPropertyTypes . These GET requests return the names and
TIds of the custom properties that are applicable for a specific type of resource. For example, this
request:
GET /api/assets/customPropertyTypes
Will return a list of custom properties available for the given client that are applicable to asset-
related APIs:
{
"totalRows": 2,
"rows": [
{
"tId": 3,
"name": "Manufacture Date"
},
{
"tId": 10,
"name": "Valve Type"
}
]
}
These TIds can be used in the query string of appropriate API endpoints; for example:
GET /api/assets/tagged/12345?customAssetPropertyTypes=3,10
The response will include a list of the properties that are defined for the given asset:
"customAssetProperties": [
{
"propertyTypeTId": 3,
"name": "Manufacture Date",
"value": "12-2011"
},
...
]
Some requests also accept a similarly structured list of custom property TIds and values in the
request body, in order to update these values for a given resource; for example:
8 of 13 20/02/2017 10:24

POST /api/customers/batch
Allows custom properties to be sent in the request as follows:
{
"items": [
{
"mId": "CUSTOMER1",
"name": "CUSTOMER1 Name",
"customProperties": [
{ "tId": 4, "value": "custom value" },
{ "tId": 7, "value": "123" }
]
}
]
}
Batch Requests
Some API endpoints have a POST /api/some/path/batch request variation that supports batch
processing. Batch requests are useful for creating or updating a large number of entities in
TrackAbout, such as for synchronizing data from an accounting system. Batch endpoints use a
common pattern for request and response body structure, and typically have some shared
processing steps, response semantics, and HTTP status codes.
Request Body
A batch request body is simply a wrapper around a corresponding PUT or POST request for a
single entity. For example, the PUT request to create or update a single pending order looks like
this:
PUT /api/orders/pending/ORDER1
{
"orderType": "CustomerDelivery",
"customer": { "mId": "CUSTOMER1" }, ...
}
The batch request for pending orders uses the same structure, repeated in a list:
POST /api/orders/pending/batch
{
"items": [
{
"orderNumber": "ORDER1",
"orderType": "CustomerDelivery",
"customer": { "mId": "CUSTOMER1" }, ...
},
{
"orderNumber": "ORDER2", ...
}, ...
]
}
Note that the verb for a batch request is always POST , even though in this case the single-entity
request uses PUT .
Batch Request Processing
Batch API endpoints are typically designed to allow continuing processing if some items in the
batch fail validation or cause business logic violations. Each item in the batch request is validated
separately, and any items that fail validation are not further processed, and the validation failure is
reported in the response. However, there are some checks that will cause the entire request to fail
with a 4xx status code: insufficient permissions, empty request, request with too many items,
invalid JSON syntax, etc.
9 of 13 20/02/2017 10:24

Batch requests are processed synchronously; the server will not return a response until all items are
processed.
Response Body
All batch API endpoints have the same response structure:
200 OK
{
"items": [
{
"status": "Success",
"identity": "ORDER1"
},
{
"status": "Failed",
"identity": "ORDER2",
"errorCode": "ValidationFailure",
"errorMessage": "Customer is required"
}
]
}
The items list in the response will have one element for each item in the request. The status
property indicates whether the item was successfully processed, and the other properties help to
identify the item and any errors encountered.
Note that the status code for this response is 200 OK , even though there are some validation
errors: this means that the batch request as a whole was understood and the server was able to
attempt processing every item. Non-200 responses only occur when the entire request is rejected,
as described further above, or when there is an unexpected runtime error.
Status Codes and Errors
Each response from the TrackAbout API will include a standard numeric HTTP status code that
describes the overall result of the operation. The response body may include more details about
the result of the operation or any errors encountered. Status codes in the 200–299 range indicate
success, 400–499 indicate a problem with the content or meaning of the request that the client
provided, and 500–599 indicate a problem with the server.
200 - OK
This is the generic status code for a successfully processed request.
201 - Created
The resource was successfully created as requested. The response may contain information about
the newly-created resource. This is only returned for POST requests.
204 - No Content
The request was successfully processed, and the response body is empty. This may be returned for
some PUT or PATCH or DELETE requests where there is no additional information to return.
400 - Bad Request
There is either a problem with the formatting of the json or it may not have passed basic validation
rules. For example, when sending the following request:
POST https://test.trackabout.com/api/trucks/123/assets/loadedAt/987 HTTP/1.1
...
{
"userEntryStartDate": "2013-04-23T18:58:17Z",
"userEntryEndDate": "2013-04-23T19:05:16Z",
"assets": {
10 of 13 20/02/2017 10:24

"tagged": [
{
"timeEntered": "2013-04-23T18:59:03Z"
}
]
}
}
The response returned may be similar to the following. Notice how it is indicating two errors with
the request.
The first asset did not have a tag or serial number associated with it1.
The location tId specified in the url (987) does not exist in the system.2.
HTTP/1.1 400 ValidationFailure
...
{
"responseStatus": {
"errorCode": "AssetMustBeIdentified",
"message": "Either the tag or serial number must be specified for each asset.",
"errors": [
{
"errorCode": "AssetMustBeIdentified",
"fieldName": "Assets.Tagged[0].Tag",
"message": "Either the tag or serial number must be specified for each asset."
},
{
"errorCode": "InvalidLocation",
"fieldName": "LocationTId",
"message": "This field must identify a valid location"
}
]
}
}
401 - Unauthorized
The credentials supplied for the request are either incorrect or invalid or missing. Refer to the
authentication section above for instructions on setting this up.
403 - Forbidden
You do not have the appropriate permissions to perform the attempted operation, or the types of
credentials provided are not supported for that operation. The response may contain the
permissions that you require. Contact support for configuring permissions.
404 - Not Found
The API endpoint does not exist, or a resource identified in the URL does not exist, or the URL is
malformed. If the URL contains a parameterized value, make sure that you are correctly setting the
value.
406 - Not Acceptable
The resource you are requesting is not available in any formats you supplied in the Accept request
header. The response contains information on accepted formats.
422 - Unprocessable Entity
The request is well formed, but was unable to be completed or validated due to business logic
constraints, missing data, etc. For example, a value provided in the request body (such as a barcode
or lot number) does not match a pattern required by business rules configured for the client, or a
resource identified in the request body (such as for a location or customer) does not exist in the
TrackAbout system.
500 - Internal Server Error
11 of 13 20/02/2017 10:24

There was an unexpected problem processing your request. Please contact TrackAbout Support if
the problem persists.
Sample Requests
Note: Depending on what client you’re using to form HTTP requests, you may need to put
two carriage returns after the headers in a GET request to signify an empty request body.
Get a List of Trucks
In this example, the TIds and names of all “truck” locations are returned in the response.
Request:
GET https://test.trackabout.com/api/trucks HTTP/1.1
Connection: close
Response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Wed, 24 Apr 2013 18:53:32 GMT
Connection: close
Content-Length: 127
{
"totalRows": 3,
"rows": [{
"tId": 456,
"name": "Little Red Truck"
}, {
"tId": 123,
}, {
"tId": 789,
}
]
}
Perform a Load Truck
In this example, a Load Truck record is created with 2 tagged assets and 1 not scanned asset, for
truck TId 123 and branch location TId 72. The response contains a confirmation message and
record ID.
Request:
POST https://test.trackabout.com/api/trucks/123/assets/loadedAt/72 HTTP/1.1
X-Impersonate-User: username2
Content-Type: application/json
Connection: close
{
"userEntryStartDate": "2013-04-23T18:58:17-05:00",
"userEntryEndDate": "2013-04-23T19:05:16-05:00",
"assets": {
"tagged": [
{
"tag": {"entryMethod":"scanned","value":"000003957"},
12 of 13 20/02/2017 10:24

"timeEntered": "2013-04-23T18:59:03-05:00"
},
{
"tag": {"entryMethod":"manual","value":"230939403"},
"timeEntered": "2013-04-23T18:59:27-05:00"
}
],
"notscanned": [
{
"productCodeTId": 87,
"quantity": 1
}
]
}
}
Response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Wed, 24 Apr 2013 18:53:32 GMT
Connection: close
Content-Length: 166
{
"message": "LoadTruck performed on 2 tagged asset(s) for truck 123, as of
2013-04-24 19:00:11Z.",
"links": [
{
"relation": "record",
"uri": "/api/records/truckLoads/41984"
}
]
}
© 2015, TrackAbout, Inc. All rights reserved.
Contact GitHub API Training Shop Blog About© 2017 GitHub, Inc. Terms Privacy Security Status Help
13 of 13 20/02/2017 10:24

Api wiki · git hub

More Related Content

What's hot

Similar to Api wiki · git hub

Recently uploaded

Api wiki · git hub