Issue #3194233 by paul121: Upload files via the API

docs/development/api/changes.md

@@ -6,9 +6,9 @@ farmOS 1.x used the [RESTful Web Services](https://drupal.org/project/restws)
 module, which provided API endpoints for each entity type (asset, log, taxonomy
 term, etc).
 
-farmOS 2.x uses the new JSON:API module included with Drupal core, which
-follows the [JSON:API](https://jsonapi.org/) specification for defining API
-resources.
+farmOS 2.x uses the new [JSON:API](https://www.drupal.org/docs/core-modules-and-themes/core-modules/jsonapi-module)
+module included with Drupal core, which follows the [JSON:API](https://jsonapi.org/)
+specification for defining API resources.
 
 The root API endpoint is `/api`.
 
@@ -372,3 +372,29 @@ resource name of `quantity--quantity`. In order to add a quantity to a new or
 existing log, they must be created in a separate API request before they can be
 referenced by the log. Quantities still have `measure`, `value`, `unit` and
 `label` fields.
+
+### Files
+
+farmOS 1.x used the [RESTful Web Services File](https://www.drupal.org/project/restws_file)
+module to enable file uploads via the API. The API accepted an array of
+base64-encoded strings to be included in the JSON body payload of the host
+entity.
+
+In farmOS 2.x, file uploads are supported by the core JSON:API module. Instead
+of base64-encoded strings, the API requires a separate `POST` of binary data
+for each file to upload. This reflects "real" PHP upload semantics, allowing
+for faster and larger file uploads via the API. This also means that files
+cannot be uploaded in the same request that creates an entity. Instead, a file
+can be uploaded to an *existing entity* in a single request, or the file can be
+uploaded and assigned to an entity in two separate requests. Refer to the
+[Drupal.org JSON:API File Uploads documentation](https://www.drupal.org/docs/core-modules-and-themes/core-modules/jsonapi-module/file-uploads)
+for more information.
+
+For example, to upload an image file to an existing observation log with `curl`:
+
+    curl https://example.com/api/log/observation/{UUID}/image \
+       -H 'Accept: application/vnd.api+json' \
+       -H 'Content-Type: application/octet-stream' \
+       -H 'Content-Disposition: attachment; filename="observation.jpg"' \
+       -H 'Authorization: Bearer …………' \
+       --data-binary @/path/to/observation.jpg

modules/core/api/src/EventSubscriber/CorsResponseEventSubscriber.php

@@ -74,7 +74,7 @@ class CorsResponseEventSubscriber implements EventSubscriberInterface {
       $response = $event->getResponse();
       $response->headers->set('Access-Control-Allow-Origin', $request_origin, TRUE);
       $response->headers->set('Access-Control-Allow-Credentials', 'true', TRUE);
-      $response->headers->set('Access-Control-Allow-Headers', 'Content-Type,Authorization,X-CSRF-Token', TRUE);
+      $response->headers->set('Access-Control-Allow-Headers', 'Content-Type,Content-Disposition,Authorization,X-CSRF-Token', TRUE);
       $response->headers->set('Access-Control-Allow-Methods', 'GET,POST,PUT,DELETE,HEAD,OPTIONS', TRUE);
       $response->headers->set('Vary', 'Origin', TRUE);
     }

modules/core/api/tests/src/Functional/CorsResponseEventSubscriberTest.php

@@ -106,7 +106,7 @@ class CorsResponseEventSubscriberTest extends FarmBrowserTestBase {
     $cors_headers = [
       'Access-Control-Allow-Origin' => $origin,
       'Access-Control-Allow-Credentials' => 'true',
-      'Access-Control-Allow-Headers' => 'Content-Type,Authorization,X-CSRF-Token',
+      'Access-Control-Allow-Headers' => 'Content-Type,Content-Disposition,Authorization,X-CSRF-Token',
       'Access-Control-Allow-Methods' => 'GET,POST,PUT,DELETE,HEAD,OPTIONS',
       'Vary' => 'Origin',
     ];