Add /files endpoint and entry type

docs/api_reference/models/files.md

@@ -0,0 +1,5 @@
+# files
+
+::: optimade.models.files
+    options:
+      show_if_no_docstring: true

docs/api_reference/server/mappers/files.md

@@ -0,0 +1,3 @@
+# files
+
+::: optimade.server.mappers.files

docs/api_reference/server/routers/files.md

@@ -0,0 +1,3 @@
+# files
+
+::: optimade.server.routers.files

docs/getting_started/setting_up_an_api.md

@@ -138,6 +138,32 @@ Currently, the reference server is not flexible enough to use custom response cl
     By default, the reference server will validate the incoming query parameters against these classes.
     If you want to use custom query parameters without redefining the classes mentioned above, you can disable this behaviour by setting the configuration option [`validate_query_parameters`][optimade.server.config.ServerConfig.validate_query_parameters] to false, after which all query parameters will be passed on to the corresponding router method (e.g., database queries).
 
+## Serving the `files` endpoint
+
+The `files` entry type describes individual files (e.g., raw data, structure files, supplementary material) and is populated in exactly the same way as the other entry types: each entry is a document in the configured collection (the collection name defaults to `files`, configurable via [`files_collection`][optimade.server.config.ServerConfig.files_collection]).
+
+A minimal `files` entry needs an `id` plus the attributes defined by [`FileResourceAttributes`](../api_reference/models/files.md#optimade.models.files.FileResourceAttributes). The most important of these is `url`, which **must** point at the actual byte stream of the file:
+
+```json
+{
+  "id": "file_1",
+  "type": "files",
+  "attributes": {
+    "last_modified": "2023-01-15T08:30:00Z",
+    "url": "https://example.org/files/cifs/1000000.cif",
+    "name": "1000000.cif",
+    "media_type": "chemical/x-cif",
+    "size": 4096
+  }
+}
+```
+
+!!! warning "Serving the file contents is your responsibility"
+    The reference server only serves the **metadata** about each file; it does not (yet) serve the file contents themselves.
+    It is up to you, the implementer, to ensure that the `url` of each entry resolves to the actual contents of the file (a byte stream, not a preview or landing page), and that it stays accessible.
+    The `url` can point anywhere the file is hosted — object storage, a static file server, a CDN, a reverse proxy in front of this API etc., as long as a client can retrieve the bytes directly from it.
+
+
 ## Validating your implementation
 
 With the database collections, mappers, aliases and provider configured, you can try running the web server (with e.g., `uvicorn optimade.server.main:app`, if your app is in the same file as the reference server) and validating it as an OPTIMADE API, following the [validation guide](../concepts/validation.md).

docs/static/default_config.json

@@ -4,6 +4,7 @@
     "mongo_database": "optimade",
     "mongo_uri": "localhost:27017",
     "links_collection": "links",
+    "files_collection": "files",
     "references_collection": "references",
     "structures_collection": "structures",
     "page_limit": 20,

openapi/index_openapi.json

@@ -500,6 +500,17 @@
               }
             ],
             "description": "Object containing links to relationships with entries of the `structures` type."
+          },
+          "files": {
+            "anyOf": [
+              {
+                "$ref": "#/components/schemas/FileRelationship"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Object containing links to relationships with entries of the `files` type."
           }
         },
         "type": "object",
@@ -845,6 +856,53 @@
         "title": "ErrorSource",
         "description": "an object containing references to the source of the error"
       },
+      "FileRelationship": {
+        "properties": {
+          "links": {
+            "anyOf": [
+              {
+                "$ref": "#/components/schemas/RelationshipLinks"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "a links object containing at least one of the following: self, related"
+          },
+          "data": {
+            "anyOf": [
+              {
+                "$ref": "#/components/schemas/BaseRelationshipResource"
+              },
+              {
+                "items": {
+                  "$ref": "#/components/schemas/BaseRelationshipResource"
+                },
+                "type": "array"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "uniqueItems": true,
+            "title": "Data",
+            "description": "Resource linkage"
+          },
+          "meta": {
+            "anyOf": [
+              {
+                "$ref": "#/components/schemas/Meta"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "a meta object that contains non-standard meta-information about the relationship."
+          }
+        },
+        "type": "object",
+        "title": "FileRelationship"
+      },
       "Implementation": {
         "properties": {
           "name": {