Introducing API 4.4

I’m super-excited to tell you about the latest version of DADI API, which we’ve been working on for the past two months. For this release, we’ve focused on two key areas: handling media files and validation. Read along, if you please.

🔗Media file metadata

API is capable of processing the upload of any type of file, such as images or videos, and referencing them from regular documents – think of a document representing a movie with a field for its poster image. When processing an uploaded file, API will generate a document with the file path and URL, along with some basic metadata properties, like the file size and its MIME type.

In version 4.4.0, we’re adding support for arbitrary metadata properties in media objects, which makes it possible for the user to add their custom metadata, such as _alt text_, a caption or copyright information. This information is sent to API at the time of upload, or any time thereafter using an update request. When the media object is retrieved, the user-defined metadata is served alongside the data generated by API.

GET /media/58576e72bafa53b625aebd4f HTTP/1.1
Host: api.somedomain.tech
Content-Type: application/json
Authorization: Bearer 8df4a823-1e1e-4bc4-800c-97bb480ccbbe

{
  "\_createdAt": 1482124902978,
  "\_createdBy": "some-client-key",
  "\_version": 1,
  "\_id": "58576e72bafa53b625aebd4f",
  "fileName": "harry-potter.jpg",
  "mimetype": "image/jpeg",
  "width": 1920,
  "height": 1080,
  "path": "workspace/media/2016/12/19/harry-potter.jpg",
  "contentLength": 173685,
  "url": "https://api.somedomain.tech/media/2016/12/19/harry-potter.jpg",
  "caption": "Movie poster for Harry Potter and the Philosopher's Stone"
}

🔗A new field type for media

Historically, referencing media files from standard collections is done with the Reference field type, a generic DADI API construct that allows a document to reference one or multiple documents from another collection. As part of our plan to improve how API handles media files, we started working on a new way for this relationship to be established, one that would be more intuitive and provide more power and flexibility.

The result is a brand new field type called Media. It can work just like a Reference field, in that it can receive references in the form of one or more document IDs, but it can do much more.

Taking the new media object metadata support to a whole new level, we’ve added support for metadata on media objects at a document level. In other words, different documents referencing a media object can contain their own metadata properties that extend the ones coming from the referenced object.

To illustrate that with an example, let’s go back to the poster image we’ve uploaded for the Harry Potter movie. When referencing that image from a movies collection, the metadata properties we added at the time of upload are probably sufficient, as they’re fairly generic. But we might also want to reference the same media object from the actors collection. In a document representing Emma Watson, we want to use the same image, but with a twist: it needs to store a set of crop coordinates that focus the image on Hermione’s face, along with a new caption that talks specifically about her character.

To do this, we can set a metadata object alongside the media object ID as the value of the Media field. When the document is retrieved, the value of the field will be composed and the document-level metadata properties will be mixed with the original ones.

POST /1.0/cinedadi/actors HTTP/1.1
Host: api.somedomain.tech
Content-Type: application/json
Authorization: Bearer 8df4a823-1e1e-4bc4-800c-97bb480ccbbe

{
  "name": "Emma Watson",
  "image": {
    "\_id": "58576e72bafa53b625aebd4f",
    "caption": "Hermione in the Gryffindor common room",
    "crop": \[16, 32, 64, 128\]
  }
}
```

GET /1.0/cinedadi/actors/58576e72bafa53b625aebd1a HTTP/1.1
Host: api.somedomain.tech
Content-Type: application/json
Authorization: Bearer 8df4a823-1e1e-4bc4-800c-97bb480ccbbe
{
“_id”: “58576e72bafa53b625aebd1a”,
“name”: “Emma Watson”,
“image”: {
“_createdAt”: 1482124902978,
“_createdBy”: “some-client-key”,
“_version”: 1,
“_id”: “58576e72bafa53b625aebd4f”,
“fileName”: “harry-potter.jpg”,
“mimetype”: “image/jpeg”,
“width”: 1920,
“height”: 1080,
“path”: “workspace/media/2016/12/19/harry-potter.jpg”,
“contentLength”:173685,
“url”: “https://api.somedomain.tech/media/2016/12/19/harry-potter.jpg",
“caption”: “Hermione sitting in the Gryffindor common room”,
“crop”: [16, 32, 64, 128]
}
}
`

🔗Other media improvements

As part of the 4.4.0 release, we’ve also added support for bulk upload of media files, different options for updating media objects and the ability to delete media objects by query.

🔗Improved document validation

When inserting or updating documents, API performs a series of checks to ensure that each field receives a value that is compatible with its type and with any validation rules defined in the collection schema. In version 4.4.0, we’ve added a series of new validation operators specific to certain field types, such as DateTime, Media and Number, with others to follow in upcoming releases.

Also, we’ve extracted the validation logic from the core application into a separate npm module, so that it becomes easier to validate documents before they are even sent to API (say, in Publish). By making the exact same validation logic available to both the core application and any third-party applications that interact with it, we can ensure that documents are validated in a consistent way, even as new field types and operators are added.

🔗Start your engines

If this sounds interesting, update your existing installation to version 4.4.0 or check how you can spin up a fresh installation if you’re new to the family.