Skip to content

metadata

V2 metadata API endpoints for v2 format operations.

router module-attribute 

router = APIRouter(
    responses={404: {"description": "Not found"}}
)

last_updated_route_subpath module-attribute 

last_updated_route_subpath = '/last_updated'

category_last_updated_route_subpath module-attribute 

category_last_updated_route_subpath = (
    "/{model_category_name}/last_updated"
)

metadata_route_subpath module-attribute 

metadata_route_subpath = '/metadata'

category_metadata_route_subpath module-attribute 

category_metadata_route_subpath = '/{model_category_name}'

LastUpdatedResponse

Bases: BaseModel

Response for /last_updated endpoint.

Source code in src/horde_model_reference/service/v2/routers/metadata.py 
23
24
25
26
class LastUpdatedResponse(BaseModel):
    """Response for /last_updated endpoint."""

    last_updated: int | None

last_updated instance-attribute 

last_updated: int | None

CategoryLastUpdatedResponse

Bases: BaseModel

Response for /{category}/last_updated endpoint.

Source code in src/horde_model_reference/service/v2/routers/metadata.py 
29
30
31
32
33
class CategoryLastUpdatedResponse(BaseModel):
    """Response for /{category}/last_updated endpoint."""

    category: str
    last_updated: int | None

category instance-attribute 

category: str

last_updated instance-attribute 

last_updated: int | None

read_v2_last_updated async 

read_v2_last_updated(
    manager: Annotated[
        ModelReferenceManager,
        Depends(get_model_reference_manager),
    ],
) -> LastUpdatedResponse

Get the last update timestamp for the canonical format.

This endpoint returns the maximum last_updated timestamp across all categories for v2 format operations. Only available when canonical_format='v2'.

Returns:

  • LastUpdatedResponse –

    LastUpdatedResponse with the maximum timestamp, or None if no metadata exists.

Raises:

  • HTTPException –

    503 if metadata is not supported or canonical_format != 'v2'.

Source code in src/horde_model_reference/service/v2/routers/metadata.py 
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
@router.get(
    last_updated_route_subpath,
    response_model=LastUpdatedResponse,
    summary="Get last update timestamp for canonical format (v2)",
    operation_id="read_v2_last_updated",
    responses={
        200: {
            "description": "Last updated timestamp",
            "links": {
                "GetAllV2Metadata": {
                    "operationId": "read_all_v2_metadata",
                    "description": "Get all v2 format metadata for all categories.",
                },
            },
        },
        503: {"description": "Service unavailable (metadata not supported or non-canonical format)"},
    },
    tags=["v2", "metadata"],
)
async def read_v2_last_updated(
    manager: Annotated[ModelReferenceManager, Depends(get_model_reference_manager)],
) -> LastUpdatedResponse:
    """Get the last update timestamp for the canonical format.

    This endpoint returns the maximum last_updated timestamp across all categories
    for v2 format operations. Only available when canonical_format='v2'.

    Returns:
        LastUpdatedResponse with the maximum timestamp, or None if no metadata exists.

    Raises:
        HTTPException: 503 if metadata is not supported or canonical_format != 'v2'.

    """
    # Check if backend supports metadata
    if not manager.backend.supports_metadata():
        raise HTTPException(
            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
            detail="Metadata tracking is not supported in REPLICA mode",
        )

    # Check if canonical format is 'v2'
    if horde_model_reference_settings.canonical_format != CanonicalFormat.v2:
        raise HTTPException(
            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
            detail=f"This endpoint is only available when canonical_format='v2'. "
            f"Current setting: canonical_format='{horde_model_reference_settings.canonical_format}'",
        )

    # Get all v2 metadata and find max timestamp
    all_metadata = manager.backend.get_all_metadata()

    if not all_metadata:
        return LastUpdatedResponse(last_updated=None)

    max_timestamp = max(
        (metadata.last_updated for metadata in all_metadata.values()),
        default=None,
    )

    return LastUpdatedResponse(last_updated=max_timestamp)

read_v2_category_last_updated async 

read_v2_category_last_updated(
    model_category_name: MODEL_REFERENCE_CATEGORY,
    manager: Annotated[
        ModelReferenceManager,
        Depends(get_model_reference_manager),
    ],
) -> CategoryLastUpdatedResponse

Get the last update timestamp for a specific category (v2 format).

Parameters:

Returns:

Raises:

  • HTTPException –

    503 if metadata is not supported.

  • HTTPException –

    404 if category has no metadata.

Source code in src/horde_model_reference/service/v2/routers/metadata.py 
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
@router.get(
    category_last_updated_route_subpath,
    response_model=CategoryLastUpdatedResponse,
    summary="Get last update timestamp for a specific category (v2)",
    operation_id="read_v2_category_last_updated",
    responses={
        200: {
            "description": "Category last updated timestamp",
            "links": {
                "GetCategoryMetadata": {
                    "operationId": "read_v2_category_metadata",
                    "parameters": {
                        "model_category_name": "$request.path.model_category_name",
                    },
                    "description": "Get full metadata for this category.",
                },
            },
        },
        404: {"description": "Category not found or no metadata available"},
        503: {"description": "Service unavailable (metadata not supported)"},
    },
    tags=["v2", "metadata"],
)
async def read_v2_category_last_updated(
    model_category_name: MODEL_REFERENCE_CATEGORY,
    manager: Annotated[ModelReferenceManager, Depends(get_model_reference_manager)],
) -> CategoryLastUpdatedResponse:
    """Get the last update timestamp for a specific category (v2 format).

    Args:
        model_category_name: The model reference category to get metadata for.
        manager: The model reference manager dependency.

    Returns:
        CategoryLastUpdatedResponse with the timestamp, or None if no metadata exists.

    Raises:
        HTTPException: 503 if metadata is not supported.
        HTTPException: 404 if category has no metadata.

    """
    # Check if backend supports metadata
    if not manager.backend.supports_metadata():
        raise HTTPException(
            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
            detail="Metadata tracking is not supported in REPLICA mode",
        )

    metadata = manager.backend.get_metadata(model_category_name)

    if metadata is None:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail=f"No v2 metadata found for category {model_category_name.value}",
        )

    return CategoryLastUpdatedResponse(
        category=model_category_name.value,
        last_updated=metadata.last_updated,
    )

read_all_v2_metadata async 

read_all_v2_metadata(
    manager: Annotated[
        ModelReferenceManager,
        Depends(get_model_reference_manager),
    ],
) -> dict[MODEL_REFERENCE_CATEGORY, CategoryMetadata]

Get all v2 format metadata.

Returns a dictionary mapping each category to its v2 format metadata.

Parameters:

Returns:

Raises:

  • HTTPException –

    503 if metadata is not supported.

Source code in src/horde_model_reference/service/v2/routers/metadata.py 
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
@router.get(
    metadata_route_subpath,
    response_model=dict[MODEL_REFERENCE_CATEGORY, CategoryMetadata],
    summary="Get all v2 format metadata",
    operation_id="read_all_v2_metadata",
    responses={
        200: {
            "description": "All v2 format metadata",
            "links": {
                "GetCategoryMetadata": {
                    "operationId": "read_v2_category_metadata",
                    "description": "Get metadata for a specific category.",
                },
                "GetLastUpdated": {
                    "operationId": "read_v2_last_updated",
                    "description": "Get the most recent update timestamp across all categories.",
                },
            },
        },
        503: {"description": "Service unavailable (metadata not supported)"},
    },
    tags=["v2", "metadata"],
)
async def read_all_v2_metadata(
    manager: Annotated[ModelReferenceManager, Depends(get_model_reference_manager)],
) -> dict[MODEL_REFERENCE_CATEGORY, CategoryMetadata]:
    """Get all v2 format metadata.

    Returns a dictionary mapping each category to its v2 format metadata.

    Args:
        manager: The model reference manager dependency.

    Returns:
        Dict of category to CategoryMetadata.

    Raises:
        HTTPException: 503 if metadata is not supported.

    """
    # Check if backend supports metadata
    if not manager.backend.supports_metadata():
        raise HTTPException(
            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
            detail="Metadata tracking is not supported in REPLICA mode",
        )

    return manager.backend.get_all_metadata()

read_v2_category_metadata async 

read_v2_category_metadata(
    model_category_name: MODEL_REFERENCE_CATEGORY,
    manager: Annotated[
        ModelReferenceManager,
        Depends(get_model_reference_manager),
    ],
) -> CategoryMetadata

Get v2 format metadata for a specific category.

Parameters:

Returns:

Raises:

  • HTTPException –

    503 if metadata is not supported.

  • HTTPException –

    404 if category has no metadata.

Source code in src/horde_model_reference/service/v2/routers/metadata.py 
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
@router.get(
    category_metadata_route_subpath,
    response_model=CategoryMetadata,
    summary="Get v2 format metadata for a specific category",
    operation_id="read_v2_category_metadata",
    responses={
        200: {
            "description": "Category metadata",
            "links": {
                "GetCategoryLastUpdated": {
                    "operationId": "read_v2_category_last_updated",
                    "parameters": {
                        "model_category_name": "$request.path.model_category_name",
                    },
                    "description": "Get just the last updated timestamp for this category.",
                },
                "GetAllMetadata": {
                    "operationId": "read_all_v2_metadata",
                    "description": "Get metadata for all categories.",
                },
            },
        },
        404: {"description": "Category not found or no metadata available"},
        503: {"description": "Service unavailable (metadata not supported)"},
    },
    tags=["v2", "metadata"],
)
async def read_v2_category_metadata(
    model_category_name: MODEL_REFERENCE_CATEGORY,
    manager: Annotated[ModelReferenceManager, Depends(get_model_reference_manager)],
) -> CategoryMetadata:
    """Get v2 format metadata for a specific category.

    Args:
        model_category_name: The model reference category to get metadata for.
        manager: The model reference manager dependency.

    Returns:
        CategoryMetadata for the category.

    Raises:
        HTTPException: 503 if metadata is not supported.
        HTTPException: 404 if category has no metadata.

    """
    # Check if backend supports metadata
    if not manager.backend.supports_metadata():
        raise HTTPException(
            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
            detail="Metadata tracking is not supported in REPLICA mode",
        )

    metadata = manager.backend.get_metadata(model_category_name)

    if metadata is None:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail=f"No v2 metadata found for category {model_category_name.value}",
        )

    return metadata