Content REST API¶

This namespace describes endpoints and data types for content operations.

Get A Release By ID¶

Get a release with a given identifier, optionally filtering out some content based on labels and zones. If the release is not found a 404 Not Found response status will be returned.

A release has a deliveryType field which indicates whether this is a ‘delta’ or a ‘full’ release. Delta releases allow updating an available ‘full’ release to a later version incrementally.

The iterationType field denotes the iteration of the release. Current values are ‘commercial’, ‘pilot’, ‘prototype’, ‘sample’ and ‘deprecated’.

A release has a tags field which is a map of key-value pairs. Tags are used to add additional information to a release, and do not necessarily follow a fixed structure. Only string keys and string values are supported.

The state field is an object which indicates whether a release is ‘published’, ‘released’, ‘recalled’ or ‘withdrawn’. A published release is not generally accessible. Released releases are accessible to customers. Recalled releases are also accessible to customer but this state indicates a problem has been reported related to this release. Withdrawn releases used to be generally accessible but were withdrawn because of a later identified issue with the release. The state object also contains a date which is the date at which the release got into the current state.

The frequencies describe the release cadence of the given release with possible values of ‘annual’, ‘yearly’, ‘semi-annual’, ‘quarterly’, ‘monthly’, ‘weekly’ or ‘daily’. Multiple values are possible.

It is possible to request a MetaLink 4 XML document which contains links to the release content. This Metalink file can be given to a number of download managers (for example aria2) which will then download the content. To receive this type of response, provide an Accept header with value application/metalink4+xml.

When downloading release content using MetaLink files and third-party download managers, make sure to pass the necessary Authentication and Authorization header. Not all download managers support this option.

Note

The names of labels and zones depends on the product family. Labels and zones that are in place and the structure of zone name is documented in the product documentation.

Endpoint	/releases/{ID}
HTTP Methods	GET
Response Content Type	`application/vnd.tomtom.mcapi+json`
Response Body	`Release`

Request Parameters¶

Name	Description	Required
id	A release id	Yes
zone	(repetitive) Only include content for zones starting with the given value	No
label	(repetitive) Only include content with labels equal to the given value	No

Example Request¶

curl -X GET 'https://example.com/releases/50?label=data&zone=WORLD.EUR.BEL'
    --header 'Accept: application/vnd.tomtom.mcapi+json'
    --header 'Authorization: Bearer <api_key>'

GET /releases/50?label=data&zone=WORLD.EUR.BEL HTTP/1.1
Host: example.com
Accept: application/vnd.tomtom.mcapi+json
Authorization: Bearer <api_key>

Example Response¶

HTTP/1.1 200
Content-Type: application/vnd.tomtom.mcapi+json

{
    "id": 50,
    "product": {
        "id": 42,
        "name": "Product Name",
        "location": "https://example.com/products/42"
    },
    "family": {
        "id": 41,
        "name": "Family Name",
        "location": "https://example.com/families/41"
    },
    "version": "2023.09.000",
    "deliveryType": "full",
    "iterationType": "prototype",
    "tags": {
        "some key": "a value"
    },
    "dueDate": "2023-11-07T10:01:29.000Z",
    "description": "standard release",
    "state": {
        "type": "released",
        "date": "2023-11-07T10:01:29.000Z",
        "reason": "reason",
    },
    "labels": ["data"],
    "zones": [{
        "name": "WORLD.EUR.BEL",
        "displayName": "Belgium"
    }],
    "contents": [{
        "id": 48,
        "name": "bel",
        "path": "/",
        "folder": true,
        "location": "https://example.com/contents/48",
        "checksum": null,
        "checksumType": null,
        "sizeBytes": 0,
        "zones": ["WORLD.EUR.BEL"],
        "labels": ["data"],
        "contents": [{
            "id": 49,
            "name": "bel.tar.gz",
            "path": "/bel",
            "folder": false,
            "location": "https://example.com/contents/49",
            "checksum": "15cb5edd330b63dc01eacde70e82d99e",
            "checksumType": "md5",
            "sizeBytes": 5429805,
            "zones": ["WORLD.EUR.BEL"],
            "labels": ["data"],
            "contents": [],
            "geoRestrictions": [],
            "action": null
        }],
        "geoRestrictions": [],
        "action": null
    }],
    "frequencies": [
        "annual",
        "quarterly"
    ]
}

Get A Release Content By ID¶

Download content for a given release ID. The client will be redirected to a download URL of the requested content. If the request content is a folder, the server will respond with HTTP status code 204 No Content. The server will set the Content-Disposition HTTP header to allow the client to save the file under the correct filename. Note that this header has to be supported by your download client.

Note

When using wget you may need to provide the ‘–content-disposition’ parameter.

Endpoint	/contents/{ID}
HTTP Methods	GET
Response Content Type	`application/octet-stream`
Response Body	`File`

Example Request¶

wget --content-disposition https://example.com/contents/49

GET /contents/49 HTTP/1.1
Host: example.com
Accept: application/octet-stream

Get a direct download link to Release Content By ID¶

In some cases a client may need a direct download url for later use. This call will generate such an URL which will have a validity period of 12 hours. It is currently not possible to customise this validity. If the requested content is a folder, the server will respond with HTTP status code 204 No Content.

Endpoint	/contents/{ID}/download-url
HTTP Methods	GET
Response Content Type	`application/json`
Response Body	`DownloadUrl`

Example Request¶

GET /contents/49/download-url HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "url": "https://download-url"
}