Media

The API's main entities allow media files to be added to them. For now media capabilities are limited to images.

Upload an image

To add an image to any of Organizer, Location or Offer issue a multipart request to their POST or PATCH endpoints with the media field of the request body being an image file.

You can send multiple files per request. Each file gets validated to be a JPG, PNG, GIF or WEBP. Other formats are not supported and will be rejected. Corrupt images will be uploaded but rejected afterwards without notice if they can not be processed.

Uploading an image this way will attach it directly to the parent entity. The response will contain a relations key media with all existing images.

For GET requests media objects can be requested using the media include.

Image renditions

After an image has been uploaded and saved to the database image renditions will be automatically created. Renditions will be created according to the following ruleset:

• If the original image is bigger than 2048px in any direction it will be contained to a 2048px square.
• If the file extension doesn't match the actual image codec the file extension will be updated accordingly
• If the image is bigger than either 1500px, 1000px or 500px a version of the image matching this size in width will be created in the same format

Those image renditions are then saved to the database and are automatically available on every media object on its renditions relations key.

Metadata

For legal reasons uploaded images need further metadata which needs to be added to a media object after upload using the v1/media routes.

Media files that don't get assigned the required metadata in a certain timeframe are automatically purged from the database.

/v1/media

Media files attached to any of Organizer, Location and Offer.

Resource

interface Media {
  id: number;
  type: "media";
  attributes: {
    url: string;
    width: number;
    height: number;
    filesize: number | null;
    format: string;
    copyright: string;
    license: string;
    createdAt: string;
    updatedAt: string;
  };
  relations: {
    translations: [
      {
        id: number;
        type: "mediatranslation";
        attributes: {
          language: "de" | "en";
          alternativeText: string;
        };
      }
    ];
    renditions?: [
      {
        id: number;
        type: "rendition";
        attributes: {
          width: number;
          height: number;
          filesize: number | null;
          format: string;
        };
      }
    ];
  };
}

Routes

Parameters	Values
-	-

GET /v1/media/{id}

Response

{
  "data": {
    "id": 3,
    "type": "media",
    "attributes": {
      "url": "http://beta.api.kulturdaten-berlin.anyvent.cloud/media/images/original/DEMO-ckst4acq7000d1vgle8iw2938-1200x800.webp",
      "width": 1200,
      "height": 800,
      "filesize": null,
      "format": "webp",
      "copyright": "Theresa Fricke",
      "license": "CC-BY",
      "expiresAt": "2021-08-29T22:45:07.000+02:00"
    },
    "relations": {
      "translations": [
        {
          "id": 3,
          "type": "mediatranslation",
          "attributes": {
            "language": "de",
            "alternativeText": "Possimus sit aut ex earum vero qui id voluptatem."
          }
        }
      ],
      "renditions": [
        {
          "id": 1,
          "type": "rendition",
          "attributes": {
            "url": "http://beta.api.kulturdaten-berlin.anyvent.cloud/media/images/renditions/DEMO-ckst4acq7000d1vgle8iw2938-1200x800-1000w.webp",
            "width": 1200,
            "height": 800,
            "filesize": null,
            "format": "webp"
          }
        },
        {
          "id": 2,
          "type": "rendition",
          "attributes": {
            "url": "http://beta.api.kulturdaten-berlin.anyvent.cloud/media/images/renditions/DEMO-ckst4acq7000d1vgle8iw2938-1200x800-500w.webp",
            "width": 1200,
            "height": 800,
            "filesize": null,
            "format": "webp"
          }
        }
      ]
    }
  },
  "meta": {
    "language": "de"
  }
}

PATCH /v1/media/{id}

Request

{
  "attributes": {
    "copyright": "Amazing photographer",
    "license": "Apache 2.0"
  }
}

Response

{
  "data": {
    "id": 1,
    "type": "media",
    "attributes": {
      "url": "http://beta.api.kulturdaten-berlin.anyvent.cloud/media/images/original/DEMO-C-ckst4ac4t00051vglgozl7kec-800x1200.webp",
      "width": 800,
      "height": 1200,
      "filesize": null,
      "format": "webp",
      "copyright": "Amazing Photographer",
      "license": "Apache 2.0",
      "expiresAt": "2021-05-14T16:28:02.000+02:00"
    },
    "relations": {
      "translations": [
        {
          "id": 1,
          "type": "mediatranslation",
          "attributes": {
            "language": "de",
            "alternativeText": "Dolore numquam aut tempora exercitationem libero et quidem molestias praesentium."
          }
        },
        {
          "id": 232,
          "type": "mediatranslation",
          "attributes": {
            "language": "en",
            "alternativeText": "Also available in english"
          }
        }
      ],
      "renditions": []
    }
  },
  "meta": {
    "language": "de"
  }
}