Discovery REST API

This namespace describes endpoints and data types for discovery operations.

List All Families

Get all product families.

Endpoint	/families
HTTP Methods	GET
Response Content Type	application/vnd.tomtom.mcapi+json
Response Body	Page<Family>

Request Parameters

Name	Description	Required
filter	OData filter	No

Example Request

curl -X GET 'https://example.com/families'
    --header 'Accept: application/vnd.tomtom.mcapi+json'
    --header 'Authorization: Bearer <api_key>'

GET /families 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

{
    "content": [{
        "id": 41,
        "name": "MultiNet-R",
        "description": "The MultiNet-R product family",
        "abbreviation": "MNR",
        "location": "https://example.com/families/10"
    }],
    "last": true,
    "totalElements": 1,
    "totalPages": 1,
    "first": true,
    "sort": null,
    "numberOfElements": 1,
    "size": 50,
    "number": 0
}

Get A Family By ID

Get a single product family by ID. The family ID is a stable identifier which can be reused and will always point to the same product family.

Endpoint	/families/{ID}
HTTP Methods	GET
Response Content Type	application/vnd.tomtom.mcapi+json
Response Body	Family

Example Request

curl -X GET 'https://example.com/families/10'
    --header 'Accept: application/vnd.tomtom.mcapi+json'
    --header 'Authorization: Bearer <api_key>'

GET /families/10 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": 10,
    "name": "MultiNet-R",
    "description": "The MultiNet-R product family",
    "abbreviation": "MNR",
    "location": "https://example.com/families/10"
}

List All Products

Get all products.

Endpoint	/products
HTTP Methods	GET
Response Content Type	application/vnd.tomtom.mcapi+json
Response Body	Page<Product>

Request Parameters

Name	Description	Required
filter	OData filter	No

Example Request

curl -X GET 'https://example.com/products'
    --header 'Accept: application/vnd.tomtom.mcapi+json'
    --header 'Authorization: Bearer <api_key>'

GET /products 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

{
    "content": [{
        "id": 42,
        "name": "EUR",
        "description": "The Europe product",
        "family": {
            "id": 41,
            "name": "The Family",
            "location": "https://example.com/families/41"
        },
        "location": "https://example.com/products/42"
    }],
    "last": true,
    "totalElements": 1,
    "totalPages": 1,
    "first": true,
    "sort": null,
    "numberOfElements": 1,
    "size": 50,
    "number": 0
}

List Products Of A Family

Get all products within the given product family.

Endpoint	/families/{ID}/products
HTTP Methods	GET
Response Content Type	application/vnd.tomtom.mcapi+json
Response Body	Page<Product>

Request Parameters

Name	Description	Required
filter	OData filter	No

Example Request

curl -X GET 'https://example.com/families/41/products'
    --header 'Accept: application/vnd.tomtom.mcapi+json'
    --header 'Authorization: Bearer <api_key>'

GET /families/41/products 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

{
    "content": [{
        "id": 42,
        "name": "EUR",
        "description": "The Europe product",
        "family": {
            "id": 41,
            "name": "The Family",
            "location": "https://example.com/families/41"
        },
        "location": "https://example.com/products/42"
    }],
    "last": true,
    "totalElements": 1,
    "totalPages": 1,
    "first": true,
    "sort": null,
    "numberOfElements": 1,
    "size": 50,
    "number": 0
}

Get A Product

Get a single product by ID. The product ID is a stable identifier which can be reused and will always point to the same product.

Endpoint	/products/{ID}
HTTP Methods	GET
Response Content Type	application/vnd.tomtom.mcapi+json
Response Body	Product

Example Request

curl -X GET 'https://example.com/products/42'
    --header 'Accept: application/vnd.tomtom.mcapi+json'
    --header 'Authorization: Bearer <api_key>'

GET /products/42 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": 42,
    "name": "EUR",
    "description": "The Europe product",
    "family": {
        "id": 41,
        "name": "The Family",
        "location": "https://example.com/families/41"
    },
    "location": "https://example.com/products/42"
}

List All Releases

Get all releases.

Endpoint	/releases
HTTP Methods	GET
Response Content Type	application/vnd.tomtom.mcapi+json
Response Body	Page<ReleaseSummary>

Request Parameters

Name	Description	Required
filter	OData filter	No

Example Request

curl -X GET 'https://example.com/releases'
    --header 'Accept: application/vnd.tomtom.mcapi+json'
    --header 'Authorization: Bearer <api_key>'

GET /releases 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

{
    "content": [{
            "id": 30,
            "product": {
                "id": 42,
                "name": "The Europe Product",
                "location": "https://example.com/products/42"
            },
            "family": {
                "id": 41,
                "name": "The Family",
                "location": "https://example.com/families/41"
            },
            "version": "2023.09.000",
            "deliveryType": "full",
            "iterationType": "prototype",
            "tags": {},
            "state": {
                "type": "released",
                "date": "2023-11-05T10:01:29.000Z",
                "reason": "reason"
            },
            "dueDate": "2023-11-01T10:01:29.000Z",
            "location": "https://example.com/releases/30"
        },
        {
            "id": 181,
            "product": {
                "id": 42,
                "name": "The Europe Product",
                "location": "https://example.com/products/42"
            },
            "family": {
                "id": 41,
                "name": "The Family",
                "location": "https://example.com/families/41"
            },
            "version": "2023.09.001",
            "deliveryType": "delta",
            "iterationType": "commercial",
            "tags": {},
            "state": {
                "type": "released",
                "date": "2023-11-07T10:01:29.000Z",
                "reason": "reason"
            },
            "dueDate": "2023-11-05T16:10:02.000Z",
            "location": "https://example.com/releases/181"
        }
    ],
    "last": true,
    "totalElements": 2,
    "totalPages": 1,
    "first": true,
    "sort": null,
    "numberOfElements": 2,
    "size": 50,
    "number": 0
}

List Releases Of A Product

Get all releases of a given product.

Endpoint	/products/{ID}/releases
HTTP Methods	GET
Response Content Type	application/vnd.tomtom.mcapi+json
Response Body	Page<ReleaseSummary>

Request Parameters

Name	Description	Required
filter	OData filter	No

Example Request

curl -X GET 'https://example.com/products/42/releases'
    --header 'Accept: application/vnd.tomtom.mcapi+json'
    --header 'Authorization: Bearer <api_key>'

GET /products/42/releases 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

{
    "content": [{
            "id": 30,
            "product": {
                "id": 42,
                "name": "The Europe Product",
                "location": "https://example.com/products/42"
            },
            "family": {
                "id": 41,
                "name": "The Family",
                "location": "https://example.com/families/41"
            },
            "version": "2023.09.000",
            "deliveryType": "full",
            "iterationType": "prototype",
            "tags": {
                "some key": "a value"
            },
            "state": {
                "type": "released",
                "date": "2023-09-07T10:01:29.000Z",
                "reason": "reason"
            },
            "location": "https://example.com/releases/30"
        },
        {
            "id": 181,
            "product": {
                "id": 42,
                "name": "The Europe Product",
                "location": "https://example.com/products/42"
            },
            "family": {
                "id": 41,
                "name": "The Family",
                "location": "https://example.com/families/41"
            },
            "version": "2023.09.001",
            "deliveryType": "delta",
            "iterationType": "commercial",
            "tags": {},
            "state": {
                "type": "released",
                "date": "2023-11-07T10:01:29.000Z",
                "reason": "reason"
            },
            "location": "https://example.com/releases/181"
        }
    ],
    "last": true,
    "totalElements": 2,
    "totalPages": 1,
    "first": true,
    "sort": null,
    "numberOfElements": 2,
    "size": 50,
    "number": 0
}

List Latest Releases Of A Family

Get latest releases of a given product family.

Endpoint	/families/{ID}/latest-releases
HTTP Methods	GET
Response Content Type	application/vnd.tomtom.mcapi+json
Response Body	LatestFamilyReleases

Request Parameters

Name	Description	Required
filter	OData filter	No

Example Request

curl -X GET 'https://example.com/families/10/latest-releases'
    --header 'Accept: application/vnd.tomtom.mcapi+json'
    --header 'Authorization: Bearer <api_key>'

GET /families/1/latest-releases 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

{
    "products": [
        {
            "product": {
                "id": 2,
                "family": {
                    "id": 1,
                    "name": "Family",
                    "location": "https://example.com/families/1"
                },
                "name": "EUR",
                "description": "Europe",
                "location": "https://example.com/products/2"
            },
            "releases": [{
                "id": 3,
                "version": "2023.03.000",
                "deliveryType": "full",
                "iterationType": "commercial",
                "tags": {},
                "location": "https://example.com/releases/3",
                "state": "released"
            },
            {
                "id": 4,
                "version": "2023.03.000",
                "deliveryType": "delta",
                "iterationType": "commercial",
                "tags": {},
                "location": "https://example.com/releases/4",
                "state": "released"
            },
            {
                "id": 5,
                "version": "2023.03.000",
                "deliveryType": "delta",
                "iterationType": "sample",
                "tags": {
                    "some key": "a value"
                },
                "location": "https://example.com/releases/5",
                "state": "released"
            }]
        },
        {
            "product": {
                "id": 2,
                "family": {
                    "id": 1,
                    "name": "Family",
                    "location": "https://example.com/families/1"
                },
                "name": "NAM",
                "location": "https://example.com/products/2"
            },
            "releases": [{
                "id": 3,
                "version": "2023.05.004",
                "deliveryType": "full",
                "iterationType": "commercial",
                "tags": {},
                "location": "https://example.com/releases/3",
                "state": "released"
            }]
        }
    ]
}

Example Request With Filter

curl -X GET 'https://example.com/families/10/latest-releases?filter=product.name eq \'EUR\' and releases.iterationType eq \'commercial\''
    --header 'Accept: application/vnd.tomtom.mcapi+json'
    --header 'Authorization: Bearer <api_key>'

GET /families/1/latest-releases?filter=product.name eq 'EUR' and releases.iterationType eq 'commercial' 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

{
    "products": [
        {
            "product": {
                "id": 2,
                "family": {
                    "id": 1,
                    "name": "Family",
                    "location": "https://example.com/families/1"
                },
                "name": "EUR",
                "description": "Europe",
                "location": "https://example.com/products/2"
            },
            "releases": [{
                "id": 3,
                "version": "2023.03.000",
                "deliveryType": "full",
                "iterationType": "commercial",
                "tags": {},
                "location": "https://example.com/releases/3",
                "state": "released"
            },
            {
                "id": 4,
                "version": "2023.03.000",
                "deliveryType": "delta",
                "iterationType": "commercial",
                "tags": {},
                "location": "https://example.com/releases/4",
                "state": "released"
            }]
        }
    ]
}