Working with Trackmatic RESTful API

#Getting Started All requests to the Trackmatic REST API conform to the following structure http(s)://{servername}/api/{version}/{area}/{resource}/{action}?{query_parameters}

{servername}

The server which you are connecting to.

{version}

The version of the API which you are programming against. Currently there is only one version indicated by “v1”.

{area}

The area of the API which you wish to connect to. Currently the API is broken down into the following areas:

• core – The area home to all core Trackmatic resources.
• routing – Home to all routing related resources
• team – Home to all resources relating to the TEAM system
• utility – Provides a number of utility resources
• vortex – Home to resources from the vortex system
• tracking – Home to tracking related components

Additional areas may be added as further functionality is added.

{resource}

The resource which you want to perform an action against. i.e. client, vehicle

{action}

The action indicates the specific task you wish to perform on the supplied resource. An action is associated with an HTTP method, i.e. you would need to either GET, POST, PUT or DELETE to a specific resources. The {action} is used to indicate actions which are not part of the HTTP standard. For instance, if you wish to assign a driver to a vehicle the URL would appear as follows: http://rest.trackmatic.co.za/api/v1/core/vehicles/assign?id=XYZ123GP&driverId=1

{query_parameters}

A request may require one or more query parameters which would be supplied according to the HTTP standard. The remainder of the document will detail each area and the relevant resources, actions and parameters. The headings of the following sections are in line with the URL of the resource. A table will follow indicating the query parameters required and the HTTP method to use for each action.

#Content Types

Currently the API supports two content types, “application/json” and “application/xml”. This gives you the ability to choose the format you wish to use to consume data from the API. The content type is controlled via the “Content-Type” header as per the RESTful guidelines.

#The Client ID

The Trackmatic API is based around 2 entities, contacts and clients. A contact is an individual who has been given a username and password. The API call "api/v1/core/security/authenticate" authenticates the contact and returns a cookie which identifies that contact for any future calls. A contact may be assigned to one or more clients, and a client may have one or more contacts. A Client is the entity which vehicles are assigned to. Any information pertaining to vehicles is stored against the client record.

The Trackmatic API requires you to indicate which client you are performing any action against. You can do this in one of 2 ways:

• Supply the client ID in the http header, i.e. "clientId: 88"
• Supply the client ID as part of the query string i.e. "[some url]/?clientId=88"

Both approaches achieve the same result. A full http request would appear as follows:

GET http://rest.trackmatic.co.za/api/v1/core/vehicles/get HTTP/1.1
Host: rest.trackmatic.co.za
Connection: keep-alive
clientId: 88
User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/536.5 (KHTML, like Gecko) Chrome/19.0.1084.52 Safari/536.5
Content-Type: application/json
Accept: */*
Accept-Encoding: gzip,deflate,sdch
Accept-Language: en-GB,en-US;q=0.8,en;q=0.6
Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.3
Cookie:     .ASPXFORMSAUTH=17124E9F942ADED8E8EF6AB765D9A3FF20A9F950CB4946D4BF6F02CB1EC422C43801EC49F85B9625AD5B23D89ABABA56E582B25D86684385F6B926BB2DF087869197F28F623CCE1739C0EE5C8115EF86AB48936E6C332EA62105D6B159497BBFFD153D6EAFCB1D742E930665BE216FC035D66AEF79DE44CF72AA262AD2F89561B6C0F626

#Common Application Workflow

Now that you have the basics, lets look at putting a simple application together using the Trackmatic REST API.

For this example we are going to do the following:

##Authenticate the contact

Retrieve a list of clients which that contact has access to Retrieve a list of vehicles assigned to the client record Retrieve live positions for those vehicles This explanation will make use of the API Reference Guide in order to give you more information about each call

##Authenticating the user

In order to perform any calls against the API you must be authenticated. Authentication is required to restrict access to only the information you have permission to view/edit. The restrictions are performed at a contact level. To view which permissions you have assigned see /permissions.

For a full explanation on the Authentication call see /wiki/api/v1/core/security/authenticate

Next > Security