Introduction¶

This is a guide to the TrackMan Range Server API. Various topics are covered, including authenticating users, starting a play session and getting real-time measurements.

Root Endpoint¶

You can issue a GET request to the root endpoint to get all the endpoint categories that the API supports. The root endpoint does not require authentication.

GET /api
Host: https://localsite.trackmanrange.com

Authentication¶

Almost all API requests must include a token that identifies the user and/or client that is accessing the specified resource. The token should be included in the Authorization header using a Bearer authorization scheme:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYmYiOjE0NzkyOTk2N

For information on acquiring an access token, refer to the Authentication section of the documentation.

Media Types¶

All API responses return data as application/json and is the only supported media type. Clients can include application/json in the Accept header of each HTTP request. All API requests that contain a body MUST include the Content-Type header with the value application/json.

Hypermedia¶

Most API responses that return a JSON result, will contain a _links property. This property may contain one or more links that point to related resources, or modify the current resource. Based on the state of the resource, different links can be present in the response object (i.e. a resource that is active, may return a deactivate link and vice-versa). Clients are expected to understand each link type and what they represent. Links with the "templated":true property can be expected to be proper RFC 6570 URI templates.

Here's an example response from creating a new player session and the links it may contain:

{
  "sessionId": "719167b8-d395-4d66-bccc-413896130cef",
  "player": {
    "id": "5be86359-073c-434b-ad2d-a3932222dabe",
    "name": "Example Player"
  },
  "bayId": "9279bee1-631b-4bc2-a5b8-62eeeeca9e5d",
  "targetId": "a43a1e52-180a-4519-95e2-373a5afff414",
  "startedAt": "2016-11-16T09:54:48.8456444Z",
  "_links": {
    "self": {
      "method": "GET",
      "href": "https://localsite.trackmanrange.com/api/session"
    },
    "endsession": {
      "method": "DELETE",
      "href": "https://localsite.trackmanrange.com/api/session"
    },
    "select_target": {
      "method": "PUT",
      "href": "https://localsite.trackmanrange.com/api/session/target"
    },
    "measurements": {
      "method": "GET",
      "href": "ws://dr-site-dev-test.azurewebsites.net/ws?type=measurements&sessionId=719167b&ticketId=6ca4e7db"
    },
    "ticket": {
      "method": "POST",
      "href": "https://localsite.trackmanrange.com/api/tickets"
    }
  }
}

Dates¶

All dates managed by the API are UTC dates serialized in json in standard ISO-8601 date/time format.

HTTP Verbs¶

Where possible, Driving Range APIs strive to use appropriate HTTP verbs for each action.

Status Codes¶

Bellow you'll find a list of common http status codes the API may return as part of a response and their meaning. You can expect these to be returned consistently throughout the API.

Pagination¶

All requests that return collections return a json object with the collection wrapped in an items array property. Results with multiple pages will be paginated to 20 items by default (though this may vary depending on the resource). You can specify further pages with the ?page parameter. For some resources, you can also set a custom page size up to 100 with the ?pageSize parameter. Note that for technical reasons not all endpoints respect the ?pageSize parameter.

Paginated results additionally include information about the current page, page size, page count and total number of items in the entire result set (where available), as well as hypermedia links for navigating the collection data. The links are named first, prev, next and last respectively, and are included only if necessary (i.e. there will be no next link if there isn't a next page).

GET /api/targets?page=3&pageSize=2

{
  "items": [
    {
      "id": "ce72011e-030d-46db-b6b4-21829b7a5502",
      "name": "Target 1",
      "description": "Target in the center",
      "createdAt": "2016-11-15T11:57:43.527Z",
      "lastUpdatedAt": "2016-11-15T11:57:43.527Z",
      "_links": {
        "self": {
          "method": "GET",
          "href": "https://localsite.trackmanrange.com/api/targets/ce72011e-030d-46db-b6b4-21829b7a5502"
        }
      }
    },
    {
      "id": "6a6b9ae2-d06b-4e21-bc36-0a2b8b33ee92",
      "name": "Target 2",
      "description": "Target in the right corner",
      "createdAt": "2016-11-15T11:58:33.537Z",
      "lastUpdatedAt": "2016-11-15T11:58:33.537Z",
      "_links": {
        "self": {
          "method": "GET",
          "href": "https://localsite.trackmanrange.com/api/targets/6a6b9ae2-d06b-4e21-bc36-0a2b8b33ee92"
        }
      }
    }
  ],
  "_links": {
    "self": {
      "method": "GET",
      "href": "https://localsite.trackmanrange.com/api/targets?page=3&pageSize=2"
    },
    "first": {
      "method": "GET",
      "href": "https://localsite.trackmanrange.com/api/targets?pageSize=2"
    },
    "prev": {
      "method": "GET",
      "href": "https://localsite.trackmanrange.com/api/targets?page=2&pageSize=2"
    },
    "next": {
      "method": "GET",
      "href": "https://localsite.trackmanrange.com/api/targets?page=4&pageSize=2"
    },
    "last": {
      "method": "GET",
      "href": "https://localsite.trackmanrange.com/api/targets?page=5&pageSize=2"
    }
  },
  "page": 3,
  "pageSize": 2,
  "pageCount": 5,
  "total": 10
}