4.2. V1 and V2 API

IGSDB v1 API

To access the legacy v1 representation of the product list or product detail, use:

Product list	https://igsdb-v2.herokuapp.com/api/v1/products
Product detail	https://igsdb-v2.herokuapp.com/api/v1/products/(product_id)
Schema	https://igsdb-v2.herokuapp.com/api/v1/schema

IGSDB v2 API

To access the newer v2 API:

Product list	https://igsdb-v2.herokuapp.com/api/v2/products
Product detail	https://igsdb-v2.herokuapp.com/api/v2/products/(token)
Schema	https://igsdb-v2.herokuapp.com/api/v2/schema

API changes between v1 and v2

The IGSDB data model evolved significantly in v2. For backward compatibility, the v1 endpoints remain available, but new development should target v2.

product_id vs token

In v1 each product was identified by an integer product_id, for example:

/api/v1/products/123

In v2 each product is identified by a human‑readable slug-like token, for example:

/api/v2/products/clr-3

Tokens are stable, descriptive, and easier to use across systems (e.g. submission tools).

v1 API support in v2

The v1 API is still exposed for older tools. Important differences and caveats:

1. product_id is no longer a dedicated persisted field; it maps to the current primary key and is not guaranteed stable over time.
2. Responses differ depending on the presence of filters (see below).

Product ID not guaranteed

Since v2 uses token as the canonical identifier, the product_id in v1 responses may change if rows are recreated or reordered. For any durable integration, prefer the v2 token.

v1 product list behavior (caching & pagination)

The v1 products list endpoint behaves differently based on query parameters:

• No query parameters: Returns an array of all products (no pagination) from a prebuilt cache.
• ?type=glazing or ?type=shading: Returns all matching products (no pagination) from a type‑specific cache.
• Any other filter (e.g. ?subtype=monolithic, ?name=clear, etc.): Returns a paginated response.

When cache data is not yet built, the endpoint returns a 503 response and triggers an asynchronous rebuild. Retry after a short delay.

Paginated v1 Response Structure

For filtered (non‑simple) queries the response includes pagination keys:

{
    "page": 1,
    "page_size": 100,
    "total_pages": 42,
    "count": 4200,
    "next": "/api/v1/products/?page=2&subtype=monolithic",
    "previous": null,
    "products": [
        {
            "product_id": 1,
            "token": "clr-3",
            "nfrc_id": "123456",
            ...
        },
        ...
    ]
}

For simple queries (no filters or only type) the response is just an array:

[
    {
        "product_id": 1,
        "token": "clr-3",
        ...
    },
    ...
]