diff --git a/optimade/server/entry_collections/entry_collections.py b/optimade/server/entry_collections/entry_collections.py index 2ddb3d5ae1..a549c949de 100644 --- a/optimade/server/entry_collections/entry_collections.py +++ b/optimade/server/entry_collections/entry_collections.py @@ -16,7 +16,7 @@ class EntryCollection(ABC): """ Backend-agnostic base class for querying collections of - [`EntryResource`][optimade.models.EntryResource]s. """ + [`EntryResource`][optimade.models.entries.EntryResource]s. """ def __init__( self, @@ -44,6 +44,9 @@ def __init__( self.resource_mapper = resource_mapper self.transformer = transformer + self.provider_prefix = CONFIG.provider.prefix + self.provider_fields = CONFIG.provider_fields.get(resource_mapper.ENDPOINT, []) + @abstractmethod def __len__(self) -> int: """ Returns the total number of entries in the collection. """ @@ -65,8 +68,9 @@ def find( """ Fetches results and indicates if more data is available. - Also gives the total number of data available in the absence of - [`page_limit`][optimade.server.query_params.EntryListingQueryParams.page_limit]. + Also gives the total number of data available in the absence of `page_limit`. + See [`EntryListingQueryParams`][optimade.server.query_params.EntryListingQueryParams] + for more information. Parameters: params (EntryListingQueryParams): entry listing URL query params diff --git a/optimade/server/entry_collections/mongo.py b/optimade/server/entry_collections/mongo.py index 5b896bb8d3..8a19800a85 100644 --- a/optimade/server/entry_collections/mongo.py +++ b/optimade/server/entry_collections/mongo.py @@ -33,7 +33,7 @@ class MongoCollection(EntryCollection): """ Class for querying MongoDB collections (implemented by either pymongo or mongomock) - containing serialized [`EntryResource`][optimade.models.EntryResource]s objects. + containing serialized [`EntryResource`][optimade.models.entries.EntryResource]s objects. """ @@ -64,8 +64,6 @@ def __init__( MongoTransformer(mapper=resource_mapper), ) - self.provider_prefix = CONFIG.provider.prefix - self.provider_fields = CONFIG.provider_fields.get(resource_mapper.ENDPOINT, []) self.parser = LarkParser( version=(0, 10, 1), variant="default" ) # The MongoTransformer only supports v0.10.1 as the latest grammar diff --git a/optimade/server/query_params.py b/optimade/server/query_params.py index 477e85c6fe..7acd6e9028 100644 --- a/optimade/server/query_params.py +++ b/optimade/server/query_params.py @@ -5,7 +5,71 @@ class EntryListingQueryParams: - """Common query params for all Entry listing endpoints.""" + """ + 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/` endpoint MUST include, + for each field name `` in its `data.properties.` 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 (int): 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 (int): 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`. + + """ def __init__( self, @@ -82,7 +146,38 @@ def __init__( class SingleEntryQueryParams: - """Common query params for single entry endpoints.""" + """ + 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`. + + """ def __init__( self,