Skip to content

references

CONFIG: ServerConfig = ServerConfig() module-attribute

This singleton loads the config from a hierarchy of sources (see customise_sources) and makes it importable in the server code.

ERROR_RESPONSES: Optional[dict[int, dict[str, Any]]] = {err.status_code: {'model': ErrorResponse, 'description': err.title}for err in POSSIBLE_ERRORS} module-attribute

references_coll = create_collection(name=CONFIG.references_collection, resource_cls=ReferenceResource, resource_mapper=ReferenceMapper) module-attribute

router = APIRouter(redirect_slashes=True) module-attribute

EntryListingQueryParams

Bases: BaseQueryParams

Common query params for all Entry listing endpoints.

Attributes:

Name Type Description
filter str

A filter string, in the format described in section API Filtering Format Specification of the specification.
response_format str

The output format requested (see section Response Format). Defaults to the format string 'json', which specifies the standard output format described in this specification.

Example: http://example.com/v1/structures?response_format=xml
email_address EmailStr

An email address of the user making the request. The email SHOULD be that of a person and not an automatic system.

Example: http://example.com/v1/structures?email_address=user@example.com
response_fields str

A comma-delimited set of fields to be provided in the output. If provided, these fields MUST be returned along with the REQUIRED fields. Other OPTIONAL fields MUST NOT be returned when this parameter is present.

Example: http://example.com/v1/structures?response_fields=last_modified,nsites
sort str

If supporting sortable queries, an implementation MUST use the sort query parameter with format as specified by JSON API 1.0.

An implementation MAY support multiple sort fields for a single query. If it does, it again MUST conform to the JSON API 1.0 specification.

If an implementation supports sorting for an entry listing endpoint, then the /info/<entries> endpoint MUST include, for each field name <fieldname> in its data.properties.<fieldname> response value that can be used for sorting, the key sortable with value true. If a field name under an entry listing endpoint supporting sorting cannot be used for sorting, the server MUST either leave out the sortable key or set it equal to false for the specific field name. The set of field names, with sortable equal to true are allowed to be used in the "sort fields" list according to its definition in the JSON API 1.0 specification. The field sortable is in addition to each property description and other OPTIONAL fields. An example is shown in the section Entry Listing Info Endpoints.
page_limit int

Sets a numerical limit on the number of entries returned. See JSON API 1.0. The API implementation MUST return no more than the number specified. It MAY return fewer. The database MAY have a maximum limit and not accept larger numbers (in which case an error code -- 403 Forbidden -- MUST be returned). The default limit value is up to the API implementation to decide.

Example: http://example.com/optimade/v1/structures?page_limit=100
page_offset int

RECOMMENDED for use with offset-based pagination: using page_offset and page_limit is RECOMMENDED.

Example: Skip 50 structures and fetch up to 100: /structures?page_offset=50&page_limit=100.
page_number int

RECOMMENDED for use with page-based pagination: using page_number and page_limit is RECOMMENDED. It is RECOMMENDED that the first page has number 1, i.e., that page_number is 1-based.

Example: Fetch page 2 of up to 50 structures per page: /structures?page_number=2&page_limit=50.
page_cursor int

RECOMMENDED for use with cursor-based pagination: using page_cursor and page_limit is RECOMMENDED.
page_above str

RECOMMENDED for use with value-based pagination: using page_above/page_below and page_limit is RECOMMENDED.

Example: Fetch up to 100 structures above sort-field value 4000 (in this example, server chooses to fetch results sorted by increasing id, so page_above value refers to an id value): /structures?page_above=4000&page_limit=100.
page_below str

RECOMMENDED for use with value-based pagination: using page_above/page_below and page_limit is RECOMMENDED.
include str

A server MAY implement the JSON API concept of returning compound documents by utilizing the include query parameter as specified by JSON API 1.0.

All related resource objects MUST be returned as part of an array value for the top-level included field, see the section JSON Response Schema: Common Fields.

The value of include MUST be a comma-separated list of "relationship paths", as defined in the JSON API. If relationship paths are not supported, or a server is unable to identify a relationship path a 400 Bad Request response MUST be made.

The default value for include is references. This means references entries MUST always be included under the top-level field included as default, since a server assumes if include is not specified by a client in the request, it is still specified as include=references. Note, if a client explicitly specifies include and leaves out references, references resource objects MUST NOT be included under the top-level field included, as per the definition of included, see section JSON Response Schema: Common Fields.

Note: A query with the parameter include set to the empty string means no related resource objects are to be returned under the top-level field included.
api_hint str

If the client provides the parameter, the value SHOULD have the format vMAJOR or vMAJOR.MINOR, where MAJOR is a major version and MINOR is a minor version of the API. For example, if a client appends api_hint=v1.0 to the query string, the hint provided is for major version 1 and minor version 0.
Source code in optimade/server/query_params.py 
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
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
177
178
179
180
181
182
183
184
185
186
187
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
236
237
238
239
240
241
242
243
244
245
246
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
class EntryListingQueryParams(BaseQueryParams):
    """
    Common query params for all Entry listing endpoints.

    Attributes:
        filter (str): A filter string, in the format described in section API Filtering Format Specification of the specification.

        response_format (str): The output format requested (see section Response Format).
            Defaults to the format string 'json', which specifies the standard output format described in this specification.

            **Example**: `http://example.com/v1/structures?response_format=xml`

        email_address (EmailStr): An email address of the user making the request.
            The email SHOULD be that of a person and not an automatic system.

            **Example**: `http://example.com/v1/structures?email_address=user@example.com`

        response_fields (str): A comma-delimited set of fields to be provided in the output.
            If provided, these fields MUST be returned along with the REQUIRED fields.
            Other OPTIONAL fields MUST NOT be returned when this parameter is present.

            **Example**: `http://example.com/v1/structures?response_fields=last_modified,nsites`

        sort (str): If supporting sortable queries, an implementation MUST use the `sort` query parameter with format as specified
            by [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-sorting).

            An implementation MAY support multiple sort fields for a single query.
            If it does, it again MUST conform to the JSON API 1.0 specification.

            If an implementation supports sorting for an entry listing endpoint, then the `/info/<entries>` endpoint MUST include,
            for each field name `<fieldname>` in its `data.properties.<fieldname>` response value that can be used for sorting,
            the key `sortable` with value `true`.
            If a field name under an entry listing endpoint supporting sorting cannot be used for sorting, the server MUST either
            leave out the `sortable` key or set it equal to `false` for the specific field name.
            The set of field names, with `sortable` equal to `true` are allowed to be used in the "sort fields" list according to
            its definition in the JSON API 1.0 specification.
            The field `sortable` is in addition to each property description and other OPTIONAL fields.
            An example is shown in the section Entry Listing Info Endpoints.

        page_limit (int): Sets a numerical limit on the number of entries returned.
            See [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-pagination).
            The API implementation MUST return no more than the number specified.
            It MAY return fewer. The database MAY have a maximum limit and not accept larger numbers
            (in which case an error code -- `403 Forbidden` -- MUST be returned).
            The default limit value is up to the API implementation to decide.

            **Example**: `http://example.com/optimade/v1/structures?page_limit=100`

        page_offset (int): RECOMMENDED for use with _offset-based_ pagination: using `page_offset` and `page_limit` is RECOMMENDED.

            **Example**: Skip 50 structures and fetch up to 100: `/structures?page_offset=50&page_limit=100`.

        page_number (int): RECOMMENDED for use with _page-based_ pagination: using `page_number` and `page_limit` is RECOMMENDED.
            It is RECOMMENDED that the first page has number 1, i.e., that `page_number` is 1-based.

            **Example**: Fetch page 2 of up to 50 structures per page: `/structures?page_number=2&page_limit=50`.

        page_cursor (int): RECOMMENDED for use with _cursor-based_ pagination: using `page_cursor` and `page_limit` is RECOMMENDED.

        page_above (str): RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED.

            **Example**: Fetch up to 100 structures above sort-field value 4000 (in this example, server chooses to fetch results sorted by
            increasing `id`, so `page_above` value refers to an `id` value): `/structures?page_above=4000&page_limit=100`.

        page_below (str): RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED.

        include (str): A server MAY implement the JSON API concept of returning [compound documents](https://jsonapi.org/format/1.0/#document-compound-documents)
            by utilizing the `include` query parameter as specified by [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-includes).

            All related resource objects MUST be returned as part of an array value for the top-level `included` field,
            see the section JSON Response Schema: Common Fields.

            The value of `include` MUST be a comma-separated list of "relationship paths", as defined in the [JSON API](https://jsonapi.org/format/1.0/#fetching-includes).
            If relationship paths are not supported, or a server is unable to identify a relationship path a `400 Bad Request` response MUST be made.

            The **default value** for `include` is `references`. This means `references` entries MUST always be included under the top-level field
            `included` as default, since a server assumes if `include` is not specified by a client in the request, it is still specified as `include=references`.
            Note, if a client explicitly specifies `include` and leaves out `references`, `references` resource objects MUST NOT be included under the top-level
            field `included`, as per the definition of `included`, see section JSON Response Schema: Common Fields.

            **Note**: A query with the parameter `include` set to the empty string means no related resource objects are to be returned under the top-level field `included`.

        api_hint (str): If the client provides the parameter, the value SHOULD have the format `vMAJOR` or `vMAJOR.MINOR`,
            where MAJOR is a major version and MINOR is a minor version of the API.
            For example, if a client appends `api_hint=v1.0` to the query string, the hint provided is for major version 1 and minor version 0.

    """

    # The reference server implementation only supports offset/number-based pagination
    unsupported_params: list[str] = [
        "page_cursor",
        "page_below",
    ]

    def __init__(
        self,
        *,
        filter: Annotated[
            str,
            Query(  # pylint: disable=redefined-builtin
                description="A filter string, in the format described in section API Filtering Format Specification of the specification.",
            ),
        ] = "",
        response_format: Annotated[
            str,
            Query(
                description="The output format requested (see section Response Format).\nDefaults to the format string 'json', which specifies the standard output format described in this specification.\nExample: `http://example.com/v1/structures?response_format=xml`",
            ),
        ] = "json",
        email_address: Annotated[
            EmailStr,
            Query(
                description="An email address of the user making the request.\nThe email SHOULD be that of a person and not an automatic system.\nExample: `http://example.com/v1/structures?email_address=user@example.com`",
            ),
        ] = "",
        response_fields: Annotated[
            str,
            Query(
                description="A comma-delimited set of fields to be provided in the output.\nIf provided, these fields MUST be returned along with the REQUIRED fields.\nOther OPTIONAL fields MUST NOT be returned when this parameter is present.\nExample: `http://example.com/v1/structures?response_fields=last_modified,nsites`",
                pattern=r"([a-z_][a-z_0-9]*(,[a-z_][a-z_0-9]*)*)?",
            ),
        ] = "",
        sort: Annotated[
            str,
            Query(
                description='If supporting sortable queries, an implementation MUST use the `sort` query parameter with format as specified by [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-sorting).\n\nAn implementation MAY support multiple sort fields for a single query.\nIf it does, it again MUST conform to the JSON API 1.0 specification.\n\nIf an implementation supports sorting for an entry listing endpoint, then the `/info/<entries>` endpoint MUST include, for each field name `<fieldname>` in its `data.properties.<fieldname>` response value that can be used for sorting, the key `sortable` with value `true`.\nIf a field name under an entry listing endpoint supporting sorting cannot be used for sorting, the server MUST either leave out the `sortable` key or set it equal to `false` for the specific field name.\nThe set of field names, with `sortable` equal to `true` are allowed to be used in the "sort fields" list according to its definition in the JSON API 1.0 specification.\nThe field `sortable` is in addition to each property description and other OPTIONAL fields.\nAn example is shown in the section Entry Listing Info Endpoints.',
                pattern=r"([a-z_][a-z_0-9]*(,[a-z_][a-z_0-9]*)*)?",
            ),
        ] = "",
        page_limit: Annotated[
            int,
            Query(
                description="Sets a numerical limit on the number of entries returned.\nSee [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-pagination).\nThe API implementation MUST return no more than the number specified.\nIt MAY return fewer.\nThe database MAY have a maximum limit and not accept larger numbers (in which case an error code -- 403 Forbidden -- MUST be returned).\nThe default limit value is up to the API implementation to decide.\nExample: `http://example.com/optimade/v1/structures?page_limit=100`",
                ge=0,
            ),
        ] = CONFIG.page_limit,
        page_offset: Annotated[
            int,
            Query(
                description="RECOMMENDED for use with _offset-based_ pagination: using `page_offset` and `page_limit` is RECOMMENDED.\nExample: Skip 50 structures and fetch up to 100: `/structures?page_offset=50&page_limit=100`.",
                ge=0,
            ),
        ] = 0,
        page_number: Annotated[
            int,
            Query(
                description="RECOMMENDED for use with _page-based_ pagination: using `page_number` and `page_limit` is RECOMMENDED.\nIt is RECOMMENDED that the first page has number 1, i.e., that `page_number` is 1-based.\nExample: Fetch page 2 of up to 50 structures per page: `/structures?page_number=2&page_limit=50`.",
                # ge=1,  # This constraint is only 'RECOMMENDED' in the specification, so should not be included here or in the OpenAPI schema
            ),
        ] = None,  # type: ignore[assignment]
        page_cursor: Annotated[
            int,
            Query(
                description="RECOMMENDED for use with _cursor-based_ pagination: using `page_cursor` and `page_limit` is RECOMMENDED.",
                ge=0,
            ),
        ] = 0,
        page_above: Annotated[
            str,
            Query(
                description="RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED.\nExample: Fetch up to 100 structures above sort-field value 4000 (in this example, server chooses to fetch results sorted by increasing `id`, so `page_above` value refers to an `id` value): `/structures?page_above=4000&page_limit=100`.",
            ),
        ] = None,  # type: ignore[assignment]
        page_below: Annotated[
            str,
            Query(
                description="RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED.",
            ),
        ] = None,  # type: ignore[assignment]
        include: Annotated[
            str,
            Query(
                description='A server MAY implement the JSON API concept of returning [compound documents](https://jsonapi.org/format/1.0/#document-compound-documents) by utilizing the `include` query parameter as specified by [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-includes).\n\nAll related resource objects MUST be returned as part of an array value for the top-level `included` field, see the section JSON Response Schema: Common Fields.\n\nThe value of `include` MUST be a comma-separated list of "relationship paths", as defined in the [JSON API](https://jsonapi.org/format/1.0/#fetching-includes).\nIf relationship paths are not supported, or a server is unable to identify a relationship path a `400 Bad Request` response MUST be made.\n\nThe **default value** for `include` is `references`.\nThis means `references` entries MUST always be included under the top-level field `included` as default, since a server assumes if `include` is not specified by a client in the request, it is still specified as `include=references`.\nNote, if a client explicitly specifies `include` and leaves out `references`, `references` resource objects MUST NOT be included under the top-level field `included`, as per the definition of `included`, see section JSON Response Schema: Common Fields.\n\n> **Note**: A query with the parameter `include` set to the empty string means no related resource objects are to be returned under the top-level field `included`.',
            ),
        ] = "references",
        api_hint: Annotated[
            str,
            Query(
                description="If the client provides the parameter, the value SHOULD have the format `vMAJOR` or `vMAJOR.MINOR`, where MAJOR is a major version and MINOR is a minor version of the API. For example, if a client appends `api_hint=v1.0` to the query string, the hint provided is for major version 1 and minor version 0.",
                pattern=r"(v[0-9]+(\.[0-9]+)?)?",
            ),
        ] = "",
    ):
        self.filter = filter
        self.response_format = response_format
        self.email_address = email_address
        self.response_fields = response_fields
        self.sort = sort
        self.page_limit = page_limit
        self.page_offset = page_offset
        self.page_number = page_number
        self.page_cursor = page_cursor
        self.page_above = page_above
        self.page_below = page_below
        self.include = include
        self.api_hint = api_hint

check_params(query_params)

This method checks whether all the query parameters that are specified in the URL string are implemented in the relevant *QueryParams class.

This method handles four cases:

  • If a query parameter is passed that is not defined in the relevant *QueryParams class, and it is not prefixed with a known provider prefix, then a BadRequest is raised.
  • If a query parameter is passed that is not defined in the relevant *QueryParams class, that is prefixed with a known provider prefix, then the parameter is silently ignored
  • If a query parameter is passed that is not defined in the relevant *QueryParams class, that is prefixed with an unknown provider prefix, then a UnknownProviderQueryParameter warning is emitted.
  • If a query parameter is passed that is on the unsupported_params list for the inherited class, then a QueryParamNotUsed warning is emitted.

Parameters:

Name Type Description Default
query_params Iterable[str]

An iterable of the request's string query parameters.

 required

Raises:

Type Description
`BadRequest`

if the query parameter was not found in the relevant class, or if it does not have a valid prefix.
Source code in optimade/server/query_params.py 
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
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
def check_params(self, query_params: Iterable[str]) -> None:
    """This method checks whether all the query parameters that are specified
    in the URL string are implemented in the relevant `*QueryParams` class.

    This method handles four cases:

    * If a query parameter is passed that is not defined in the relevant `*QueryParams` class,
      and it is not prefixed with a known provider prefix, then a `BadRequest` is raised.
    * If a query parameter is passed that is not defined in the relevant `*QueryParams` class,
      that is prefixed with a known provider prefix, then the parameter is silently ignored
    * If a query parameter is passed that is not defined in the relevant `*QueryParams` class,
      that is prefixed with an unknown provider prefix, then a `UnknownProviderQueryParameter`
      warning is emitted.
    * If a query parameter is passed that is on the `unsupported_params` list for the inherited
      class, then a `QueryParamNotUsed` warning is emitted.

    Arguments:
        query_params: An iterable of the request's string query parameters.

    Raises:
        `BadRequest`: if the query parameter was not found in the relevant class, or if it
            does not have a valid prefix.

    """
    if not getattr(CONFIG, "validate_query_parameters", False):
        return
    errors = []
    warnings = []
    unsupported_warnings = []
    for param in query_params:
        if param in self.unsupported_params:
            unsupported_warnings.append(param)
        if not hasattr(self, param):
            split_param = param.split("_")
            if param.startswith("_") and len(split_param) > 2:
                prefix = split_param[1]
                if prefix in BaseResourceMapper.SUPPORTED_PREFIXES:
                    errors.append(param)
                elif prefix not in BaseResourceMapper.KNOWN_PROVIDER_PREFIXES:
                    warnings.append(param)
            else:
                errors.append(param)

    if warnings:
        warn(
            f"The query parameter(s) '{warnings}' are unrecognised and have been ignored.",
            UnknownProviderQueryParameter,
        )

    if unsupported_warnings:
        warn(
            f"The query parameter(s) '{unsupported_warnings}' are not supported by this server and have been ignored.",
            QueryParamNotUsed,
        )

    if errors:
        raise BadRequest(
            f"The query parameter(s) '{errors}' are not recognised by this endpoint."
        )

ReferenceMapper

Bases: BaseResourceMapper

Source code in optimade/server/mappers/references.py 
7
8
class ReferenceMapper(BaseResourceMapper):
    ENTRY_RESOURCE_CLASS = ReferenceResource

ALL_ATTRIBUTES()

Returns all attributes served by this entry.

Source code in optimade/server/mappers/entries.py 
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
@classproperty
def ALL_ATTRIBUTES(cls) -> set[str]:
    """Returns all attributes served by this entry."""
    from optimade.server.config import CONFIG

    return (
        set(cls.ENTRY_RESOURCE_ATTRIBUTES)
        .union(
            cls.get_optimade_field(field)
            for field in CONFIG.provider_fields.get(cls.ENDPOINT, ())
            if isinstance(field, str)
        )
        .union(
            cls.get_optimade_field(field["name"])
            for field in CONFIG.provider_fields.get(cls.ENDPOINT, ())
            if isinstance(field, dict)
        )
        .union({cls.get_optimade_field(field) for field in cls.PROVIDER_FIELDS})
    )

ENDPOINT() cached

Returns the expected endpoint for this mapper, corresponding to the type property of the resource class.

Source code in optimade/server/mappers/entries.py 
161
162
163
164
165
166
167
168
169
170
171
@classproperty
@lru_cache(maxsize=NUM_ENTRY_TYPES)
def ENDPOINT(cls) -> str:
    """Returns the expected endpoint for this mapper, corresponding
    to the `type` property of the resource class.

    """
    endpoint = cls.ENTRY_RESOURCE_CLASS.model_fields["type"].default
    if not endpoint and not isinstance(endpoint, str):
        raise ValueError("Type not set for this entry type!")
    return endpoint

ENTRY_RESOURCE_ATTRIBUTES()

Returns the dictionary of attributes defined by the underlying entry resource class.

Source code in optimade/server/mappers/entries.py 
154
155
156
157
158
159
@classproperty
def ENTRY_RESOURCE_ATTRIBUTES(cls) -> dict[str, Any]:
    """Returns the dictionary of attributes defined by the underlying entry resource class."""
    from optimade.server.schemas import retrieve_queryable_properties

    return retrieve_queryable_properties(cls.ENTRY_RESOURCE_CLASS)

SUPPORTED_PREFIXES() cached

A set of prefixes handled by this entry type.

Note

This implementation only includes the provider prefix, but in the future this property may be extended to include other namespaces (for serving fields from, e.g., other providers or domain-specific terms).

Source code in optimade/server/mappers/entries.py 
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
@classproperty
@lru_cache(maxsize=1)
def SUPPORTED_PREFIXES(cls) -> set[str]:
    """A set of prefixes handled by this entry type.

    !!! note
        This implementation only includes the provider prefix,
        but in the future this property may be extended to include other
        namespaces (for serving fields from, e.g., other providers or
        domain-specific terms).

    """
    from optimade.server.config import CONFIG

    return {CONFIG.provider.prefix}

alias_for(field) cached classmethod

Return aliased field name.

Deprecated

This method is deprecated could be removed without further warning. Please use get_backend_field().

Parameters:

Name Type Description Default
field str

OPTIMADE field name.

 required

Returns:

Type Description
str

Aliased field as found in all_aliases().
Source code in optimade/server/mappers/entries.py 
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
@classmethod
@lru_cache(maxsize=128)
def alias_for(cls, field: str) -> str:
    """Return aliased field name.

    !!! warning "Deprecated"
        This method is deprecated could be removed without further warning. Please use
        [`get_backend_field()`][optimade.server.mappers.entries.BaseResourceMapper.get_backend_field].

    Parameters:
        field: OPTIMADE field name.

    Returns:
        Aliased field as found in [`all_aliases()`][optimade.server.mappers.entries.BaseResourceMapper.all_aliases].

    """
    warnings.warn(
        "The `.alias_for(...)` method is deprecated, please use `.get_backend_field(...)`.",
        DeprecationWarning,
    )
    return cls.get_backend_field(field)

alias_of(field) cached classmethod

Return de-aliased field name, if it exists, otherwise return the input field name.

Deprecated

This method is deprecated could be removed without further warning. Please use get_optimade_field().

Parameters:

Name Type Description Default
field str

Field name to be de-aliased.

 required

Returns:

Type Description
str

De-aliased field name, falling back to returning field.
Source code in optimade/server/mappers/entries.py 
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
@classmethod
@lru_cache(maxsize=128)
def alias_of(cls, field: str) -> str:
    """Return de-aliased field name, if it exists,
    otherwise return the input field name.

    !!! warning "Deprecated"
        This method is deprecated could be removed without further warning. Please use
        [`get_optimade_field()`][optimade.server.mappers.entries.BaseResourceMapper.get_optimade_field].

    Parameters:
        field: Field name to be de-aliased.

    Returns:
        De-aliased field name, falling back to returning `field`.

    """
    warnings.warn(
        "The `.alias_of(...)` method is deprecated, please use `.get_optimade_field(...)`.",
        DeprecationWarning,
    )
    return cls.get_optimade_field(field)

all_aliases() cached classmethod

Returns all of the associated aliases for this entry type, including those defined by the server config. The first member of each tuple is the OPTIMADE-compliant field name, the second is the backend-specific field name.

Returns:

Type Description
Iterable[tuple[str, str]]

A tuple of alias tuples.
Source code in optimade/server/mappers/entries.py 
 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
106
107
108
109
110
111
112
113
114
115
116
@classmethod
@lru_cache(maxsize=NUM_ENTRY_TYPES)
def all_aliases(cls) -> Iterable[tuple[str, str]]:
    """Returns all of the associated aliases for this entry type,
    including those defined by the server config. The first member
    of each tuple is the OPTIMADE-compliant field name, the second
    is the backend-specific field name.

    Returns:
        A tuple of alias tuples.

    """
    from optimade.server.config import CONFIG

    return (
        tuple(
            (f"_{CONFIG.provider.prefix}_{field}", field)
            if not field.startswith("_")
            else (field, field)
            for field in CONFIG.provider_fields.get(cls.ENDPOINT, [])
            if isinstance(field, str)
        )
        + tuple(
            (f"_{CONFIG.provider.prefix}_{field['name']}", field["name"])
            if not field["name"].startswith("_")
            else (field["name"], field["name"])
            for field in CONFIG.provider_fields.get(cls.ENDPOINT, [])
            if isinstance(field, dict)
        )
        + tuple(
            (f"_{CONFIG.provider.prefix}_{field}", field)
            if not field.startswith("_")
            else (field, field)
            for field in cls.PROVIDER_FIELDS
        )
        + tuple(CONFIG.aliases.get(cls.ENDPOINT, {}).items())
        + cls.ALIASES
    )

all_length_aliases() cached classmethod

Returns all of the associated length aliases for this class, including those defined by the server config.

Returns:

Type Description
tuple[tuple[str, str], ...]

A tuple of length alias tuples.
Source code in optimade/server/mappers/entries.py 
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
@classmethod
@lru_cache(maxsize=NUM_ENTRY_TYPES)
def all_length_aliases(cls) -> tuple[tuple[str, str], ...]:
    """Returns all of the associated length aliases for this class,
    including those defined by the server config.

    Returns:
        A tuple of length alias tuples.

    """
    from optimade.server.config import CONFIG

    return cls.LENGTH_ALIASES + tuple(
        CONFIG.length_aliases.get(cls.ENDPOINT, {}).items()
    )

deserialize(results) classmethod

Converts the raw database entries for this class into serialized models, mapping the data along the way.

Source code in optimade/server/mappers/entries.py 
367
368
369
370
371
372
373
374
375
376
377
378
@classmethod
def deserialize(
    cls, results: Union[dict, Iterable[dict]]
) -> Union[list[EntryResource], EntryResource]:
    """Converts the raw database entries for this class into serialized models,
    mapping the data along the way.

    """
    if isinstance(results, dict):
        return cls.ENTRY_RESOURCE_CLASS(**cls.map_back(results))

    return [cls.ENTRY_RESOURCE_CLASS(**cls.map_back(doc)) for doc in results]

get_backend_field(optimade_field) cached classmethod

Return the field name configured for the particular underlying database for the passed OPTIMADE field name, that would be used in an API filter.

Aliases are read from all_aliases().

If a dot-separated OPTIMADE field is provided, e.g., species.mass, only the first part will be mapped. This means for an (OPTIMADE, DB) alias of (species, kinds), get_backend_fields("species.mass") will return kinds.mass.

Parameters:

Name Type Description Default
optimade_field str

The OPTIMADE field to attempt to map to the backend-specific field.

 required

Examples:

>>> get_backend_field("chemical_formula_anonymous")
'formula_anon'
>>> get_backend_field("formula_anon")
'formula_anon'
>>> get_backend_field("_exmpl_custom_provider_field")
'custom_provider_field'

Returns:

Type Description
str

The mapped field name to be used in the query to the backend.
Source code in optimade/server/mappers/entries.py 
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
236
237
@classmethod
@lru_cache(maxsize=128)
def get_backend_field(cls, optimade_field: str) -> str:
    """Return the field name configured for the particular
    underlying database for the passed OPTIMADE field name, that would
    be used in an API filter.

    Aliases are read from
    [`all_aliases()`][optimade.server.mappers.entries.BaseResourceMapper.all_aliases].

    If a dot-separated OPTIMADE field is provided, e.g., `species.mass`, only the first part will be mapped.
    This means for an (OPTIMADE, DB) alias of (`species`, `kinds`), `get_backend_fields("species.mass")`
    will return `kinds.mass`.

    Arguments:
        optimade_field: The OPTIMADE field to attempt to map to the backend-specific field.

    Examples:
        >>> get_backend_field("chemical_formula_anonymous")
        'formula_anon'
        >>> get_backend_field("formula_anon")
        'formula_anon'
        >>> get_backend_field("_exmpl_custom_provider_field")
        'custom_provider_field'

    Returns:
        The mapped field name to be used in the query to the backend.

    """
    split = optimade_field.split(".")
    alias = dict(cls.all_aliases()).get(split[0], None)
    if alias is not None:
        return alias + ("." + ".".join(split[1:]) if len(split) > 1 else "")
    return optimade_field

get_optimade_field(backend_field) cached classmethod

Return the corresponding OPTIMADE field name for the underlying database field, ready to be used to construct the OPTIMADE-compliant JSON response.

Aliases are read from all_aliases().

Parameters:

Name Type Description Default
backend_field str

The backend field to attempt to map to an OPTIMADE field.

 required

Examples:

>>> get_optimade_field("chemical_formula_anonymous")
'chemical_formula_anonymous'
>>> get_optimade_field("formula_anon")
'chemical_formula_anonymous'
>>> get_optimade_field("custom_provider_field")
'_exmpl_custom_provider_field'

Returns:

Type Description
str

The mapped field name to be used in an OPTIMADE-compliant response.
Source code in optimade/server/mappers/entries.py 
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
@classmethod
@lru_cache(maxsize=128)
def get_optimade_field(cls, backend_field: str) -> str:
    """Return the corresponding OPTIMADE field name for the underlying database field,
    ready to be used to construct the OPTIMADE-compliant JSON response.

    Aliases are read from
    [`all_aliases()`][optimade.server.mappers.entries.BaseResourceMapper.all_aliases].

    Arguments:
        backend_field: The backend field to attempt to map to an OPTIMADE field.

    Examples:
        >>> get_optimade_field("chemical_formula_anonymous")
        'chemical_formula_anonymous'
        >>> get_optimade_field("formula_anon")
        'chemical_formula_anonymous'
        >>> get_optimade_field("custom_provider_field")
        '_exmpl_custom_provider_field'

    Returns:
        The mapped field name to be used in an OPTIMADE-compliant response.

    """
    return {alias: real for real, alias in cls.all_aliases()}.get(
        backend_field, backend_field
    )

get_required_fields() cached classmethod

Get REQUIRED response fields.

Returns:

Type Description
set

REQUIRED response fields.
Source code in optimade/server/mappers/entries.py 
312
313
314
315
316
317
318
319
320
321
@classmethod
@lru_cache(maxsize=NUM_ENTRY_TYPES)
def get_required_fields(cls) -> set:
    """Get REQUIRED response fields.

    Returns:
        REQUIRED response fields.

    """
    return cls.TOP_LEVEL_NON_ATTRIBUTES_FIELDS

length_alias_for(field) cached classmethod

Returns the length alias for the particular field, or None if no such alias is found.

Parameters:

Name Type Description Default
field str

OPTIMADE field name.

 required

Returns:

Type Description
Optional[str]

Aliased field as found in all_length_aliases().
Source code in optimade/server/mappers/entries.py 
189
190
191
192
193
194
195
196
197
198
199
200
201
202
@classmethod
@lru_cache(maxsize=128)
def length_alias_for(cls, field: str) -> Optional[str]:
    """Returns the length alias for the particular field,
    or `None` if no such alias is found.

    Parameters:
        field: OPTIMADE field name.

    Returns:
        Aliased field as found in [`all_length_aliases()`][optimade.server.mappers.entries.BaseResourceMapper.all_length_aliases].

    """
    return dict(cls.all_length_aliases()).get(field, None)

map_back(doc) classmethod

Map properties from MongoDB to OPTIMADE.

Starting from a MongoDB document doc, map the DB fields to the corresponding OPTIMADE fields. Then, the fields are all added to the top-level field "attributes", with the exception of other top-level fields, defined in cls.TOP_LEVEL_NON_ATTRIBUTES_FIELDS. All fields not in cls.TOP_LEVEL_NON_ATTRIBUTES_FIELDS + "attributes" will be removed. Finally, the type is given the value of the specified cls.ENDPOINT.

Parameters:

Name Type Description Default
doc dict

A resource object in MongoDB format.

 required

Returns:

Type Description
dict

A resource object in OPTIMADE format.
Source code in optimade/server/mappers/entries.py 
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
@classmethod
def map_back(cls, doc: dict) -> dict:
    """Map properties from MongoDB to OPTIMADE.

    Starting from a MongoDB document `doc`, map the DB fields to the corresponding OPTIMADE fields.
    Then, the fields are all added to the top-level field "attributes",
    with the exception of other top-level fields, defined in `cls.TOP_LEVEL_NON_ATTRIBUTES_FIELDS`.
    All fields not in `cls.TOP_LEVEL_NON_ATTRIBUTES_FIELDS` + "attributes" will be removed.
    Finally, the `type` is given the value of the specified `cls.ENDPOINT`.

    Parameters:
        doc: A resource object in MongoDB format.

    Returns:
        A resource object in OPTIMADE format.

    """
    mapping = ((real, alias) for alias, real in cls.all_aliases())
    newdoc = {}
    reals = {real for _, real in cls.all_aliases()}
    for key in doc:
        if key not in reals:
            newdoc[key] = doc[key]
    for real, alias in mapping:
        if real in doc:
            newdoc[alias] = doc[real]

    if "attributes" in newdoc:
        raise Exception("Will overwrite doc field!")
    attributes = newdoc.copy()

    for field in cls.TOP_LEVEL_NON_ATTRIBUTES_FIELDS:
        value = attributes.pop(field, None)
        if value is not None:
            newdoc[field] = value
    for field in list(newdoc.keys()):
        if field not in cls.TOP_LEVEL_NON_ATTRIBUTES_FIELDS:
            del newdoc[field]

    newdoc["type"] = cls.ENDPOINT
    newdoc["attributes"] = attributes

    return newdoc

ReferenceResource

Bases: EntryResource

The references entries describe bibliographic references.

The following properties are used to provide the bibliographic details:

  • address, annote, booktitle, chapter, crossref, edition, howpublished, institution, journal, key, month, note, number, organization, pages, publisher, school, series, title, volume, year: meanings of these properties match the BibTeX specification, values are strings;
  • bib_type: type of the reference, corresponding to type property in the BibTeX specification, value is string;
  • authors and editors: lists of person objects which are dictionaries with the following keys:
    • name: Full name of the person, REQUIRED.
    • firstname, lastname: Parts of the person's name, OPTIONAL.
  • doi and url: values are strings.
  • Requirements/Conventions:
    • Support: OPTIONAL support in implementations, i.e., any of the properties MAY be null.
    • Query: Support for queries on any of these properties is OPTIONAL. If supported, filters MAY support only a subset of comparison operators.
    • Every references entry MUST contain at least one of the properties.
Source code in optimade/models/references.py 
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
class ReferenceResource(EntryResource):
    """The `references` entries describe bibliographic references.

    The following properties are used to provide the bibliographic details:

    - **address**, **annote**, **booktitle**, **chapter**, **crossref**, **edition**, **howpublished**, **institution**, **journal**, **key**, **month**, **note**, **number**, **organization**, **pages**, **publisher**, **school**, **series**, **title**, **volume**, **year**: meanings of these properties match the [BibTeX specification](http://bibtexml.sourceforge.net/btxdoc.pdf), values are strings;
    - **bib_type**: type of the reference, corresponding to **type** property in the BibTeX specification, value is string;
    - **authors** and **editors**: lists of *person objects* which are dictionaries with the following keys:
        - **name**: Full name of the person, REQUIRED.
        - **firstname**, **lastname**: Parts of the person's name, OPTIONAL.
    - **doi** and **url**: values are strings.
    - **Requirements/Conventions**:
        - **Support**: OPTIONAL support in implementations, i.e., any of the properties MAY be `null`.
        - **Query**: Support for queries on any of these properties is OPTIONAL.
            If supported, filters MAY support only a subset of comparison operators.
        - Every references entry MUST contain at least one of the properties.

    """

    type: Annotated[
        Literal["references"],
        OptimadeField(
            description="""The name of the type of an entry.
- **Type**: string.
- **Requirements/Conventions**:
    - **Support**: MUST be supported by all implementations, MUST NOT be `null`.
    - **Query**: MUST be a queryable property with support for all mandatory filter features.
    - **Response**: REQUIRED in the response.
    - MUST be an existing entry type.
    - The entry of type <type> and ID <id> MUST be returned in response to a request for `/<type>/<id>` under the versioned base URL.
- **Example**: `"structures"`""",
            pattern="^references$",
            support=SupportLevel.MUST,
            queryable=SupportLevel.MUST,
        ),
    ] = "references"
    attributes: ReferenceResourceAttributes

    @field_validator("attributes", mode="before")
    @classmethod
    def validate_attributes(cls, value: Any) -> dict[str, Any]:
        if not isinstance(value, dict):
            if isinstance(value, BaseModel):
                value = value.model_dump()
            else:
                raise TypeError("attributes field must be a mapping")
        if not any(prop[1] is not None for prop in value):
            raise ValueError("reference object must have at least one field defined")
        return value

ReferenceResponseMany

Bases: EntryResponseMany

Source code in optimade/models/responses.py 
151
152
153
154
155
156
157
158
159
class ReferenceResponseMany(EntryResponseMany):
    data: Annotated[
        Union[list[ReferenceResource], list[dict[str, Any]]],
        StrictField(
            description="List of unique OPTIMADE references entry resource objects.",
            uniqueItems=True,
            union_mode="left_to_right",
        ),
    ]

model_config = ConfigDict(json_encoders={datetime: lambda : v.astimezone(timezone.utc).strftime('%Y-%m-%dT%H:%M:%SZ')}) class-attribute instance-attribute

The specification mandates that datetimes must be encoded following RFC3339, which does not support fractional seconds, thus they must be stripped in the response. This can cause issues when the underlying database contains fields that do include microseconds, as filters may return unexpected results.

either_data_meta_or_errors_must_be_set()

Overwriting the existing validation function, since 'errors' MUST NOT be set.

Source code in optimade/models/optimade_json.py 
387
388
389
390
391
392
393
394
395
396
397
398
399
400
@model_validator(mode="after")
def either_data_meta_or_errors_must_be_set(self) -> "Success":
    """Overwriting the existing validation function, since 'errors' MUST NOT be set."""
    required_fields = ("data", "meta")
    if not any(field in self.model_fields_set for field in required_fields):
        raise ValueError(
            f"At least one of {required_fields} MUST be specified in the top-level response."
        )

    # errors MUST be skipped
    if self.errors or "errors" in self.model_fields_set:
        raise ValueError("'errors' MUST be skipped for a successful response.")

    return self

ReferenceResponseOne

Bases: EntryResponseOne

Source code in optimade/models/responses.py 
141
142
143
144
145
146
147
148
class ReferenceResponseOne(EntryResponseOne):
    data: Annotated[
        Optional[Union[ReferenceResource, dict[str, Any]]],
        StrictField(
            description="A single references entry resource.",
            union_mode="left_to_right",
        ),
    ]

model_config = ConfigDict(json_encoders={datetime: lambda : v.astimezone(timezone.utc).strftime('%Y-%m-%dT%H:%M:%SZ')}) class-attribute instance-attribute

The specification mandates that datetimes must be encoded following RFC3339, which does not support fractional seconds, thus they must be stripped in the response. This can cause issues when the underlying database contains fields that do include microseconds, as filters may return unexpected results.

either_data_meta_or_errors_must_be_set()

Overwriting the existing validation function, since 'errors' MUST NOT be set.

Source code in optimade/models/optimade_json.py 
387
388
389
390
391
392
393
394
395
396
397
398
399
400
@model_validator(mode="after")
def either_data_meta_or_errors_must_be_set(self) -> "Success":
    """Overwriting the existing validation function, since 'errors' MUST NOT be set."""
    required_fields = ("data", "meta")
    if not any(field in self.model_fields_set for field in required_fields):
        raise ValueError(
            f"At least one of {required_fields} MUST be specified in the top-level response."
        )

    # errors MUST be skipped
    if self.errors or "errors" in self.model_fields_set:
        raise ValueError("'errors' MUST be skipped for a successful response.")

    return self

SingleEntryQueryParams

Bases: BaseQueryParams

Common query params for single entry endpoints.

Attributes:

Name Type Description
response_format str

The output format requested (see section Response Format). Defaults to the format string 'json', which specifies the standard output format described in this specification.

Example: http://example.com/v1/structures?response_format=xml
email_address EmailStr

An email address of the user making the request. The email SHOULD be that of a person and not an automatic system.

Example: http://example.com/v1/structures?email_address=user@example.com
response_fields str

A comma-delimited set of fields to be provided in the output. If provided, these fields MUST be returned along with the REQUIRED fields. Other OPTIONAL fields MUST NOT be returned when this parameter is present.

Example: http://example.com/v1/structures?response_fields=last_modified,nsites
include str

A server MAY implement the JSON API concept of returning compound documents by utilizing the include query parameter as specified by JSON API 1.0.

All related resource objects MUST be returned as part of an array value for the top-level included field, see the section JSON Response Schema: Common Fields.

The value of include MUST be a comma-separated list of "relationship paths", as defined in the JSON API. If relationship paths are not supported, or a server is unable to identify a relationship path a 400 Bad Request response MUST be made.

The default value for include is references. This means references entries MUST always be included under the top-level field included as default, since a server assumes if include is not specified by a client in the request, it is still specified as include=references. Note, if a client explicitly specifies include and leaves out references, references resource objects MUST NOT be included under the top-level field included, as per the definition of included, see section JSON Response Schema: Common Fields.

Note: A query with the parameter include set to the empty string means no related resource objects are to be returned under the top-level field included.
api_hint str

If the client provides the parameter, the value SHOULD have the format vMAJOR or vMAJOR.MINOR, where MAJOR is a major version and MINOR is a minor version of the API. For example, if a client appends api_hint=v1.0 to the query string, the hint provided is for major version 1 and minor version 0.
Source code in optimade/server/query_params.py 
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
class SingleEntryQueryParams(BaseQueryParams):
    """
    Common query params for single entry endpoints.

    Attributes:
        response_format (str): The output format requested (see section Response Format).
            Defaults to the format string 'json', which specifies the standard output format described in this specification.

            **Example**: `http://example.com/v1/structures?response_format=xml`

        email_address (EmailStr): An email address of the user making the request.
            The email SHOULD be that of a person and not an automatic system.

            **Example**: `http://example.com/v1/structures?email_address=user@example.com`

        response_fields (str): A comma-delimited set of fields to be provided in the output.
            If provided, these fields MUST be returned along with the REQUIRED fields.
            Other OPTIONAL fields MUST NOT be returned when this parameter is present.

            **Example**: `http://example.com/v1/structures?response_fields=last_modified,nsites`

        include (str): A server MAY implement the JSON API concept of returning [compound documents](https://jsonapi.org/format/1.0/#document-compound-documents)
            by utilizing the `include` query parameter as specified by [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-includes).

            All related resource objects MUST be returned as part of an array value for the top-level `included` field,
            see the section JSON Response Schema: Common Fields.

            The value of `include` MUST be a comma-separated list of "relationship paths", as defined in the [JSON API](https://jsonapi.org/format/1.0/#fetching-includes).
            If relationship paths are not supported, or a server is unable to identify a relationship path a `400 Bad Request` response MUST be made.

            The **default value** for `include` is `references`. This means `references` entries MUST always be included under the top-level field
            `included` as default, since a server assumes if `include` is not specified by a client in the request, it is still specified as `include=references`.
            Note, if a client explicitly specifies `include` and leaves out `references`, `references` resource objects MUST NOT be included under the top-level
            field `included`, as per the definition of `included`, see section JSON Response Schema: Common Fields.

            **Note**: A query with the parameter `include` set to the empty string means no related resource objects are to be returned under the top-level field `included`.

        api_hint (str): If the client provides the parameter, the value SHOULD have the format `vMAJOR` or `vMAJOR.MINOR`,
            where MAJOR is a major version and MINOR is a minor version of the API.
            For example, if a client appends `api_hint=v1.0` to the query string, the hint provided is for major version 1 and minor version 0.

    """

    def __init__(
        self,
        *,
        response_format: Annotated[
            str,
            Query(
                description="The output format requested (see section Response Format).\nDefaults to the format string 'json', which specifies the standard output format described in this specification.\nExample: `http://example.com/v1/structures?response_format=xml`",
            ),
        ] = "json",
        email_address: Annotated[
            EmailStr,
            Query(
                description="An email address of the user making the request.\nThe email SHOULD be that of a person and not an automatic system.\nExample: `http://example.com/v1/structures?email_address=user@example.com`",
            ),
        ] = "",
        response_fields: Annotated[
            str,
            Query(
                description="A comma-delimited set of fields to be provided in the output.\nIf provided, these fields MUST be returned along with the REQUIRED fields.\nOther OPTIONAL fields MUST NOT be returned when this parameter is present.\nExample: `http://example.com/v1/structures?response_fields=last_modified,nsites`",
                pattern=r"([a-z_][a-z_0-9]*(,[a-z_][a-z_0-9]*)*)?",
            ),
        ] = "",
        include: Annotated[
            str,
            Query(
                description='A server MAY implement the JSON API concept of returning [compound documents](https://jsonapi.org/format/1.0/#document-compound-documents) by utilizing the `include` query parameter as specified by [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-includes).\n\nAll related resource objects MUST be returned as part of an array value for the top-level `included` field, see the section JSON Response Schema: Common Fields.\n\nThe value of `include` MUST be a comma-separated list of "relationship paths", as defined in the [JSON API](https://jsonapi.org/format/1.0/#fetching-includes).\nIf relationship paths are not supported, or a server is unable to identify a relationship path a `400 Bad Request` response MUST be made.\n\nThe **default value** for `include` is `references`.\nThis means `references` entries MUST always be included under the top-level field `included` as default, since a server assumes if `include` is not specified by a client in the request, it is still specified as `include=references`.\nNote, if a client explicitly specifies `include` and leaves out `references`, `references` resource objects MUST NOT be included under the top-level field `included`, as per the definition of `included`, see section JSON Response Schema: Common Fields.\n\n> **Note**: A query with the parameter `include` set to the empty string means no related resource objects are to be returned under the top-level field `included`.',
            ),
        ] = "references",
        api_hint: Annotated[
            str,
            Query(
                description="If the client provides the parameter, the value SHOULD have the format `vMAJOR` or `vMAJOR.MINOR`, where MAJOR is a major version and MINOR is a minor version of the API. For example, if a client appends `api_hint=v1.0` to the query string, the hint provided is for major version 1 and minor version 0.",
                pattern=r"(v[0-9]+(\.[0-9]+)?)?",
            ),
        ] = "",
    ):
        self.response_format = response_format
        self.email_address = email_address
        self.response_fields = response_fields
        self.include = include
        self.api_hint = api_hint

check_params(query_params)

This method checks whether all the query parameters that are specified in the URL string are implemented in the relevant *QueryParams class.

This method handles four cases:

  • If a query parameter is passed that is not defined in the relevant *QueryParams class, and it is not prefixed with a known provider prefix, then a BadRequest is raised.
  • If a query parameter is passed that is not defined in the relevant *QueryParams class, that is prefixed with a known provider prefix, then the parameter is silently ignored
  • If a query parameter is passed that is not defined in the relevant *QueryParams class, that is prefixed with an unknown provider prefix, then a UnknownProviderQueryParameter warning is emitted.
  • If a query parameter is passed that is on the unsupported_params list for the inherited class, then a QueryParamNotUsed warning is emitted.

Parameters:

Name Type Description Default
query_params Iterable[str]

An iterable of the request's string query parameters.

 required

Raises:

Type Description
`BadRequest`

if the query parameter was not found in the relevant class, or if it does not have a valid prefix.
Source code in optimade/server/query_params.py 
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
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
def check_params(self, query_params: Iterable[str]) -> None:
    """This method checks whether all the query parameters that are specified
    in the URL string are implemented in the relevant `*QueryParams` class.

    This method handles four cases:

    * If a query parameter is passed that is not defined in the relevant `*QueryParams` class,
      and it is not prefixed with a known provider prefix, then a `BadRequest` is raised.
    * If a query parameter is passed that is not defined in the relevant `*QueryParams` class,
      that is prefixed with a known provider prefix, then the parameter is silently ignored
    * If a query parameter is passed that is not defined in the relevant `*QueryParams` class,
      that is prefixed with an unknown provider prefix, then a `UnknownProviderQueryParameter`
      warning is emitted.
    * If a query parameter is passed that is on the `unsupported_params` list for the inherited
      class, then a `QueryParamNotUsed` warning is emitted.

    Arguments:
        query_params: An iterable of the request's string query parameters.

    Raises:
        `BadRequest`: if the query parameter was not found in the relevant class, or if it
            does not have a valid prefix.

    """
    if not getattr(CONFIG, "validate_query_parameters", False):
        return
    errors = []
    warnings = []
    unsupported_warnings = []
    for param in query_params:
        if param in self.unsupported_params:
            unsupported_warnings.append(param)
        if not hasattr(self, param):
            split_param = param.split("_")
            if param.startswith("_") and len(split_param) > 2:
                prefix = split_param[1]
                if prefix in BaseResourceMapper.SUPPORTED_PREFIXES:
                    errors.append(param)
                elif prefix not in BaseResourceMapper.KNOWN_PROVIDER_PREFIXES:
                    warnings.append(param)
            else:
                errors.append(param)

    if warnings:
        warn(
            f"The query parameter(s) '{warnings}' are unrecognised and have been ignored.",
            UnknownProviderQueryParameter,
        )

    if unsupported_warnings:
        warn(
            f"The query parameter(s) '{unsupported_warnings}' are not supported by this server and have been ignored.",
            QueryParamNotUsed,
        )

    if errors:
        raise BadRequest(
            f"The query parameter(s) '{errors}' are not recognised by this endpoint."
        )

create_collection(name, resource_cls, resource_mapper)

Create an EntryCollection of the configured type, depending on the value of CONFIG.database_backend.

Parameters:

Name Type Description Default
name str

The collection name.

 required
resource_cls type[EntryResource]

The type of entry resource to be stored within the collection.

 required
resource_mapper type[BaseResourceMapper]

The associated resource mapper for that entry resource type.

 required

Returns:

Type Description
EntryCollection

The created EntryCollection.
Source code in optimade/server/entry_collections/entry_collections.py 
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
def create_collection(
    name: str,
    resource_cls: type[EntryResource],
    resource_mapper: type[BaseResourceMapper],
) -> "EntryCollection":
    """Create an `EntryCollection` of the configured type, depending on the value of
    `CONFIG.database_backend`.

    Arguments:
        name: The collection name.
        resource_cls: The type of entry resource to be stored within the collection.
        resource_mapper: The associated resource mapper for that entry resource type.

    Returns:
        The created `EntryCollection`.

    """
    if CONFIG.database_backend in (
        SupportedBackend.MONGODB,
        SupportedBackend.MONGOMOCK,
    ):
        from optimade.server.entry_collections.mongo import MongoCollection

        return MongoCollection(
            name=name,
            resource_cls=resource_cls,
            resource_mapper=resource_mapper,
        )

    if CONFIG.database_backend is SupportedBackend.ELASTIC:
        from optimade.server.entry_collections.elasticsearch import ElasticCollection

        return ElasticCollection(
            name=name,
            resource_cls=resource_cls,
            resource_mapper=resource_mapper,
        )

    raise NotImplementedError(
        f"The database backend {CONFIG.database_backend!r} is not implemented"
    )

get_entries(collection, request, params)

Generalized /{entry} endpoint getter

Source code in optimade/server/routers/utils.py 
242
243
244
245
246
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
def get_entries(
    collection: EntryCollection,
    request: Request,
    params: EntryListingQueryParams,
) -> dict[str, Any]:
    """Generalized /{entry} endpoint getter"""
    from optimade.server.routers import ENTRY_COLLECTIONS

    params.check_params(request.query_params)
    (
        results,
        data_returned,
        more_data_available,
        fields,
        include_fields,
    ) = collection.find(params)

    include = []
    if getattr(params, "include", False):
        include.extend(params.include.split(","))

    included = []
    if results is not None:
        included = get_included_relationships(results, ENTRY_COLLECTIONS, include)

    if more_data_available:
        # Deduce the `next` link from the current request
        query = urllib.parse.parse_qs(request.url.query)
        query.update(collection.get_next_query_params(params, results))

        urlencoded = urllib.parse.urlencode(query, doseq=True)
        base_url = get_base_url(request.url)

        links = ToplevelLinks(next=f"{base_url}{request.url.path}?{urlencoded}")
    else:
        links = ToplevelLinks(next=None)

    if results is not None and (fields or include_fields):
        results = handle_response_fields(results, fields, include_fields)  # type: ignore[assignment]

    return {
        "links": links,
        "data": results if results else [],
        "meta": meta_values(
            url=request.url,
            data_returned=data_returned,
            data_available=len(collection),
            more_data_available=more_data_available,
            schema=CONFIG.schema_url
            if not CONFIG.is_index
            else CONFIG.index_schema_url,
        ),
        "included": included,
    }

get_references(request, params)

Source code in optimade/server/routers/references.py 
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
@router.get(
    "/references",
    response_model=ReferenceResponseMany
    if CONFIG.validate_api_response
    else dict[str, Any],
    response_model_exclude_unset=True,
    tags=["References"],
    responses=ERROR_RESPONSES,
)
def get_references(
    request: Request, params: Annotated[EntryListingQueryParams, Depends()]
) -> dict[str, Any]:
    return get_entries(
        collection=references_coll,
        request=request,
        params=params,
    )

get_single_entry(collection, entry_id, request, params)

Source code in optimade/server/routers/utils.py 
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
def get_single_entry(
    collection: EntryCollection,
    entry_id: str,
    request: Request,
    params: SingleEntryQueryParams,
) -> dict[str, Any]:
    from optimade.server.routers import ENTRY_COLLECTIONS

    params.check_params(request.query_params)
    params.filter = f'id="{entry_id}"'  # type: ignore[attr-defined]
    (
        results,
        data_returned,
        more_data_available,
        fields,
        include_fields,
    ) = collection.find(params)

    if more_data_available:
        raise InternalServerError(
            detail=f"more_data_available MUST be False for single entry response, however it is {more_data_available}",
        )

    include = []
    if getattr(params, "include", False):
        include.extend(params.include.split(","))

    included = []
    if results is not None:
        included = get_included_relationships(results, ENTRY_COLLECTIONS, include)

    links = ToplevelLinks(next=None)

    if results is not None and (fields or include_fields):
        results = handle_response_fields(results, fields, include_fields)[0]  # type: ignore[assignment]

    return {
        "links": links,
        "data": results if results else None,
        "meta": meta_values(
            url=request.url,
            data_returned=data_returned,
            data_available=len(collection),
            more_data_available=more_data_available,
            schema=CONFIG.schema_url
            if not CONFIG.is_index
            else CONFIG.index_schema_url,
        ),
        "included": included,
    }

get_single_reference(request, entry_id, params)

Source code in optimade/server/routers/references.py 
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
@router.get(
    "/references/{entry_id:path}",
    response_model=ReferenceResponseOne
    if CONFIG.validate_api_response
    else dict[str, Any],
    response_model_exclude_unset=True,
    tags=["References"],
    responses=ERROR_RESPONSES,
)
def get_single_reference(
    request: Request,
    entry_id: str,
    params: Annotated[SingleEntryQueryParams, Depends()],
) -> dict[str, Any]:
    return get_single_entry(
        collection=references_coll,
        entry_id=entry_id,
        request=request,
        params=params,
    )