Web API

The HH Data Management web API can be used to directly access portions of the HH Data Management database without having to go through the HH Data Management client and syncing framework. This gives direct access to all data.

Table of contents

Documentation

Please visit the API endpoint documentation to see all available endpoints.

Authentication

The API supports authentication using an API key (Basic authentication). The access to the API is linked to the user account and the data rules in the permissions control how data can be accessed.

To use an API key you should supply an ApiKey header with the API key as the content. To create an API key visit the website and select the Integrations menu item:

Next, click "Add New Api Key" and enter a name for the API key and a key will be generated.

Selecting Parameters

When making a GET request to an endpoint you can pass a URL parameter called parametersToInclude that lets you specify which parameters will be included in the response. This can be useful to access related data (e.g. get the session for a runsheet or the laps) and also to limit the amount of data returned in a response to make the API calls faster. The parametersToInclude should be a comma separated list. The names of the parameters are the same as those used in the HH DM client software to access custom properties and related entities. The * symbol is used to represent all parameters. When building a response the API has the following logic:

  • if you do not provide a value for parametersToInclude or if you pass in * the APi will return:
    • all parameters of the current entity
    • the following parts of the response will be present but empty
      • collections
      • children (e.g. the RunSheet endpoint will return an empty Laps object)
      • parents (e.g. the RunSheet endpoint will return empty Car and Session objects)
    • referenced items will be populated but no parameters will be included (e.g. the RunSheet endpoint will return a Setup object with no parameters)

    here is a sample from the RunSheet endpoint:

    {
        "$type": "RunSheet",
        "Id": "54d989d4-1442-40e6-8af9-7e7662a19c18",
        "Parameters": {
            "AirTemperature": 26.0,     		       
            "SetupId": "5215b098-154a-48dd-aabf-c44af0125e2b",
            "SessionId": "c9e28903-1946-4bd5-8d89-e4236f9b527c",
            "CarId": "afd5e230-0c21-40f8-88a9-b003a21a1c93",        
            "RunName": "RUN 1",
    	** additional parameters omitted for clarify **
            "Setup": {
                "$type": "Setup",
                "Id": "5215b098-154a-48dd-aabf-c44af0125e2b",
                "Parameters": {},
                "DefinitionId": "60d5a9b2-122a-42c2-a093-f9add1ec2bb4",
                "Collections": {}
            }
    	** additional parameters omitted for clarify **
        },
        "DefinitionId": "07111622-0281-4085-8118-d82082f84007",
        "Collections": {},
        "Session": [],
        "Car": [],
        "SessionCar": [],
        "Laps": []
    }
    	

    The empty and minimal objects are returned to provide insight to users to see what each entity has access to.

  • if parameters are specified then only these parameters are provided. For example, if the parametersToInclude was set to RunName,AirTemperature then the response would look like this:

    {
        "$type": "RunSheet",
        "Id": "54d989d4-1442-40e6-8af9-7e7662a19c18",
        "Parameters": {
            "AirTemperature": 26.0,
            "RunName": "RUN 3"
        },
        "DefinitionId": "07111622-0281-4085-8118-d82082f84007",
        "Collections": {}
    }
    	
  • Referenced items can be specified using the dot notation. For example, if the parametersToInclude was set to RunName,Setup.Name then the response would look like this:

    {
        "$type": "RunSheet",
        "Id": "54d989d4-1442-40e6-8af9-7e7662a19c18",
        "Parameters": {
            "RunName": "RUN 1",
            "Setup": {
                "$type": "Setup",
                "Id": "5215b098-154a-48dd-aabf-c44af0125e2b",
                "Parameters": {
                    "Name": "SETUP 1"
                },
                "DefinitionId": "60d5a9b2-122a-42c2-a093-f9add1ec2bb4",
                "Collections": {}
            }
        },
        "DefinitionId": "07111622-0281-4085-8118-d82082f84007",
        "Collections": {}
    }
    	

    the dot notation also supports the wildcard character, so sending Setup.* to the runsheet endpoint would return all parameters from the referenced setup.

includeChildren can also be provided as a URL parameter on GET requests, however this is only present for backwards compatibility and is considered to be deprecated. It may be removed in a future release. The behaviour obtained when setting includeChildren=true is for the response to include all parameters for the first level of children for an entity.  The behaviour of this parameter can be fully replicated by specifying the children using the parametersToInclude parameter. For example setting includeChildren=true on the RunSheet endpoint is equivalent to passing parametersToInclude=Laps.*.

Setting Parameter Values

When making a POST or PUT request the body of the request should contain a JSON array called parameterUpdates. Therefore the body will have a structure like this:

{ 
  "parameterUpdates": [
    {
      "name": "string",
      "value": "string"
    }
  ]
}

Each entry in the parameterUpdates should have a name that corresponds to the parameter that is to be updated and the value should be the new value you wish to set on the entity and should always be sent as a string. For example, to update the AirTemperature and TrackTemperature of a RunSheet the body of the PUT request should look like this:

{ 
  "parameterUpdates": [
    {
      "name": "AirTemperature",
      "value": "30.0"
    },
    {
      "name": "TrackTemperature",
      "value": "35.0"
    }
  ]
}

Endpoint Descriptions

All endpoints are described in the API endpoint documentation, however for some there may be some context missing and this section will explain some of the endpoints in more detail.

Tyres/Search

The Tyres/Search endpoint allows for searching of subsets of tyres in the database in the same way as the tyre inventory in the client software. This is a GET request with a body. As shown in the API endpoint documentation, the body object should contain a property associatedModelSearchMode. Depending on the value of this property the returned tyres will belong to either the whole account, a provided championship, event, car or event/car. This property is an integer with the corresponding values:

  • 0 = Account
  • 1 = Championship
  • 2 = Event
  • 3 = Car
  • 4 = Event/Car

Depending on the value provided for associatedModelSearchMode, the appropriate ID properties should be present.

TimingIntegration

The TimingIntegration endpoints are used by the HH Timing Integration (DMI) and are designed to provide a simpler interface to update runs, laps and sectors/speed traps based on an index rather than an ID. As shown in the API endpoint documentation, all request body objects should contain the following IDs:

  • accountId
  • championshipId
  • eventId
  • sessionId
  • carId

Each body can contain an array of objects under properties that make it possible to update parameters on the run/lap/sector. These objects follow the same convention as parameter updates on the standard PUT/POST endpoints as described above.

The other parameters for various endpoints are:

  • driverId - if the driver ID is provided then the driver of the run will be updated
  • runIndex - the 0-based index of the run to be updated (i.e. for run 1, runIndex = 0)
  • stintLapNumber - the 1-based stint lap number for the lap to be updated (i.e. for the out lap of the stint, stintLapNumber = 0)
  • sectorId - when updating a sector the ID of the sector must be provided. This corresponds to the ID of the TrackSectorDefinition in the TrackConfiguration used for the current session
  • speedTrapId - when updating a speed trap the ID of the sector must be provided. This corresponds to the ID of the TrackSpeedTrapDefinition in the TrackConfiguration used for the current session
  • pitIn/OutTime - the time of day for the pit in/out. This is a date string in the extended ISO-8601 format.
  • pitIn/OutSessionTime - the session time for the pit in/out. This is a value in seconds since the start of the session.
  • shouldCreateNextRun - if this is provided as true on a pit in, then a new run will be created automatically

Still need help? Contact Us Contact Us