httk.serve.optimade.endpoints¶

Public OPTIMADE endpoint response generators.

Submodules¶

Functions¶

`generate_entry_endpoint_reply`(request, config, data[, ...])	Build a JSON:API collection response for an entry endpoint.
`generate_single_entry_endpoint_reply`(request, config, data)	Build a JSON:API single-resource response for an entry identifier.
`format_optimade_error`(ex, request, config[, version])	Format an exception as an OPTIMADE error response.
`generate_base_endpoint_reply`(request, config)	Build the HTML response for the unversioned API base endpoint.
`generate_entry_info_endpoint_reply`(request, config, ...)	Build the `/info/{entry}` response for one served entry type.
`generate_info_endpoint_reply`(request, config, schema)	Build the service `/info` response.
`generate_links_endpoint_reply`(request, config)	Build the provider-links response.
`generate_versions_endpoint_reply`(request, config)	Build the preference-ordered CSV of supported API major versions.
`generate_meta`(*, representation, api_version, config)	Build the OPTIMADE response metadata object.

Package Contents¶

httk.serve.optimade.endpoints.generate_entry_endpoint_reply(request, config, data, data_available=None, related_resolver=None)[source]¶

Build a JSON:API collection response for an entry endpoint.

Parameters:

request (httk.serve.optimade.model.request.ValidatedRequest) – Validated request controlling links and field selection.
config (httk.serve.optimade.model.config.OptimadeConfig) – Service configuration for metadata and links.
data (httk.serve.optimade.model.results.QueryResults) – Query results for the current page.
data_available (int | None) – Unfiltered endpoint total for the current instant, or None to omit it.
related_resolver (RelatedResolver | None) – Optional depth-one resolver for included resources.

Returns:

JSON:API collection document.

Return type:

dict[str, Any]

httk.serve.optimade.endpoints.generate_single_entry_endpoint_reply(request, config, data, data_available=None, related_resolver=None)[source]¶

Build a JSON:API single-resource response for an entry identifier.

Parameters:

request (httk.serve.optimade.model.request.ValidatedRequest) – Validated request controlling links and field selection.
config (httk.serve.optimade.model.config.OptimadeConfig) – Service configuration for metadata and links.
data (httk.serve.optimade.model.results.QueryResults) – Query results expected to contain at most one row.
data_available (int | None) – Unfiltered endpoint total for the current instant, or None to omit it.
related_resolver (RelatedResolver | None) – Optional depth-one resolver for included resources.

Returns:

JSON:API single-resource document.

Raises:

httk.serve.optimade.model.errors.OptimadeError – If the query yields multiple rows or another page.

Return type:

dict[str, Any]

httk.serve.optimade.endpoints.format_optimade_error(ex, request, config, version=optimade_default_version)[source]¶

Format an exception as an OPTIMADE error response.

Parameters:

ex (Exception) – Exception raised while handling the request.
request (httk.serve.optimade.model.request.RawRequest) – Raw request used to construct response metadata.
config (httk.serve.optimade.model.config.OptimadeConfig) – Service metadata configuration.
version (str) – API version to report in response metadata.

Returns:

JSON:API error response.

Return type:

httk.serve.optimade.model.request.EndpointResponse

httk.serve.optimade.endpoints.generate_base_endpoint_reply(request, config)[source]¶

Build the HTML response for the unversioned API base endpoint.

Parameters:

request (httk.serve.optimade.model.request.ValidatedRequest) – Validated request supplying the displayed API version.
config (httk.serve.optimade.model.config.OptimadeConfig) – Service configuration.

Returns:

HTML response body.

Return type:

str

httk.serve.optimade.endpoints.generate_entry_info_endpoint_reply(request, config, entry, schema)[source]¶

Build the /info/{entry} response for one served entry type.

Parameters:

request (httk.serve.optimade.model.request.ValidatedRequest) – Validated request supplying response metadata context.
config (httk.serve.optimade.model.config.OptimadeConfig) – Service metadata configuration.
entry (str) – Served entry endpoint name.
schema (httk.serve.optimade.schema.served.ServedSchema) – Served entry definitions.

Returns:

JSON:API entry-info document.

Return type:

dict[str, Any]

httk.serve.optimade.endpoints.generate_info_endpoint_reply(request, config, schema)[source]¶

Build the service /info response.

Parameters:

request (httk.serve.optimade.model.request.ValidatedRequest) – Validated request supplying the API version and base URL.
config (httk.serve.optimade.model.config.OptimadeConfig) – Service metadata and license configuration.
schema (httk.serve.optimade.schema.served.ServedSchema) – Served entry types and properties.

Returns:

JSON:API service-info document.

Return type:

dict[str, Any]

httk.serve.optimade.endpoints.generate_links_endpoint_reply(request, config)[source]¶

Build the provider-links response.

Parameters:

request (httk.serve.optimade.model.request.ValidatedRequest) – Validated request supplying response metadata context.
config (httk.serve.optimade.model.config.OptimadeConfig) – Service links and metadata configuration.

Returns:

JSON:API links document.

Return type:

dict[str, Any]

httk.serve.optimade.endpoints.generate_versions_endpoint_reply(request, config)[source]¶

Build the preference-ordered CSV of supported API major versions.

Parameters:

request (httk.serve.optimade.model.request.ValidatedRequest) – Validated request context.
config (httk.serve.optimade.model.config.OptimadeConfig) – Service configuration.

Returns:

Restricted /versions CSV body.

Return type:

str

httk.serve.optimade.endpoints.generate_meta(*, representation, api_version, config, data_returned=None, more_data_available=False, data_available=None, warnings=None, last_id=None)[source]¶

Build the OPTIMADE response metadata object.

Parameters:

representation (str) – Request representation recorded in metadata.
api_version (str) – OPTIMADE version used for the response.
config (httk.serve.optimade.model.config.OptimadeConfig) – Service metadata configuration.
data_returned (int | None) – Total data objects for the current filter query, independent of pagination.
more_data_available (bool) – Whether another page is available.
data_available (int | None) – Total data objects available in the database for the endpoint (unfiltered).
warnings (list[dict[str, Any]] | None) – Warnings already associated with the request.
last_id (str | None) – Identifier of the final returned entry.

Returns:

OPTIMADE metadata mapping.

Return type:

dict[str, Any]