Add api_hint query parameter

openapi/index_openapi.json

@@ -195,6 +195,19 @@
             },
             "name": "include",
             "in": "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.",
+            "required": false,
+            "schema": {
+              "title": "Api Hint",
+              "pattern": "(v[0-9]+(\\.[0-9]+)?)?",
+              "type": "string",
+              "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.",
+              "default": ""
+            },
+            "name": "api_hint",
+            "in": "query"
           }
         ],
         "responses": {

openapi/openapi.json

@@ -245,6 +245,19 @@
             },
             "name": "include",
             "in": "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.",
+            "required": false,
+            "schema": {
+              "title": "Api Hint",
+              "pattern": "(v[0-9]+(\\.[0-9]+)?)?",
+              "type": "string",
+              "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.",
+              "default": ""
+            },
+            "name": "api_hint",
+            "in": "query"
           }
         ],
         "responses": {
@@ -439,6 +452,19 @@
             },
             "name": "include",
             "in": "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.",
+            "required": false,
+            "schema": {
+              "title": "Api Hint",
+              "pattern": "(v[0-9]+(\\.[0-9]+)?)?",
+              "type": "string",
+              "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.",
+              "default": ""
+            },
+            "name": "api_hint",
+            "in": "query"
           }
         ],
         "responses": {
@@ -539,6 +565,19 @@
             },
             "name": "include",
             "in": "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.",
+            "required": false,
+            "schema": {
+              "title": "Api Hint",
+              "pattern": "(v[0-9]+(\\.[0-9]+)?)?",
+              "type": "string",
+              "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.",
+              "default": ""
+            },
+            "name": "api_hint",
+            "in": "query"
           }
         ],
         "responses": {
@@ -733,6 +772,19 @@
             },
             "name": "include",
             "in": "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.",
+            "required": false,
+            "schema": {
+              "title": "Api Hint",
+              "pattern": "(v[0-9]+(\\.[0-9]+)?)?",
+              "type": "string",
+              "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.",
+              "default": ""
+            },
+            "name": "api_hint",
+            "in": "query"
           }
         ],
         "responses": {
@@ -833,6 +885,19 @@
             },
             "name": "include",
             "in": "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.",
+            "required": false,
+            "schema": {
+              "title": "Api Hint",
+              "pattern": "(v[0-9]+(\\.[0-9]+)?)?",
+              "type": "string",
+              "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.",
+              "default": ""
+            },
+            "name": "api_hint",
+            "in": "query"
           }
         ],
         "responses": {

optimade/server/entry_collections/entry_collections.py

@@ -11,7 +11,7 @@
 from optimade.server.exceptions import BadRequest, Forbidden
 from optimade.server.mappers import BaseResourceMapper
 from optimade.server.query_params import EntryListingQueryParams, SingleEntryQueryParams
-from optimade.server.warnings import FieldNotRecognized
+from optimade.server.warnings import FieldValueNotRecognized
 
 
 class EntryCollection(ABC):
@@ -225,7 +225,7 @@ def parse_sort_params(self, sort_params) -> List[Tuple[str, int]]:
                 )
                 for field in unknown_fields
             ):
-                warnings.warn(error_detail, FieldNotRecognized)
+                warnings.warn(error_detail, FieldValueNotRecognized)
 
             # Otherwise, if all fields are unknown, or some fields are unknown and do not
             # have other provider prefixes, then return 400: Bad Request

optimade/server/main.py

@@ -5,7 +5,6 @@
 This is an example implementation with example data.
 To implement your own server see the documentation at https://optimade.org/optimade-python-tools.
 """
-# pylint: disable=line-too-long
 from lark.exceptions import VisitError
 
 from pydantic import ValidationError
@@ -23,6 +22,7 @@
     AddWarnings,
     CheckWronglyVersionedBaseUrls,
     EnsureQueryParamIntegrity,
+    HandleApiHint,
 )
 from optimade.server.routers import (
     info,
@@ -76,10 +76,11 @@ def load_entries(endpoint_name: str, endpoint_collection: MongoCollection):
 
 
 # Add various middleware
-app.add_middleware(AddWarnings)
 app.add_middleware(CORSMiddleware, allow_origins=["*"])
 app.add_middleware(EnsureQueryParamIntegrity)
 app.add_middleware(CheckWronglyVersionedBaseUrls)
+app.add_middleware(HandleApiHint)
+app.add_middleware(AddWarnings)
 
 
 # Add various exception handlers

optimade/server/main_index.py

@@ -5,7 +5,6 @@
 This is an example implementation with example data.
 To implement your own index meta-database server see the documentation at https://optimade.org/optimade-python-tools.
 """
-# pylint: disable=line-too-long
 import json
 
 from lark.exceptions import VisitError
@@ -24,6 +23,7 @@
     AddWarnings,
     CheckWronglyVersionedBaseUrls,
     EnsureQueryParamIntegrity,
+    HandleApiHint,
 )
 from optimade.server.routers import index_info, links, versions
 from optimade.server.routers.utils import BASE_URL_PREFIXES
@@ -71,10 +71,11 @@
 
 
 # Add various middleware
-app.add_middleware(AddWarnings)
 app.add_middleware(CORSMiddleware, allow_origins=["*"])
 app.add_middleware(EnsureQueryParamIntegrity)
 app.add_middleware(CheckWronglyVersionedBaseUrls)
+app.add_middleware(HandleApiHint)
+app.add_middleware(AddWarnings)
 
 
 # Add various exception handlers