Rest V2 vs v1 changes

Global changes

  • Basic authentication is no longer supported, only the OAuth 2.0 tokens are allowed

  • Base URL has changed from mediahaven-rest-api/ to mediahaven-rest-api/v2

  • application/json is now the default output of the API

  • MediaObjectId is renamed to RecordId (MediaObjectId is still available in API)

  • All record/media endpoints now support RecordId

  • All paged results now follow the same format

    1 2 3 4 5 6 7 8 "NrOfResults" : 25 "TotalNrOfResults": 34, "StartIndex": 0, "Results": [ { ... } ]

Media /records endpoint

  • /media endpoint has changed to /records

  • Metadata-only records can now be created by sending the metadata as body (XML and JSON is supported)

Creation

Media BREAKING

Uploaded files are now handled differently and do not follow the same flow as REST v1. Instead they are processed via a workflow process. A property workflow is available to start the correct process The default flow for MediaHaven 2.0 is media_upload.

For customers that wish to use the old flow, the workflow property needs to be set to Ingest-1.0. This is needed for customers that have custom plugins in the pretranscoder.

Fragments 21.3

Fragments no longer have a dedicated endpoint for creation. Instead they can be created via the records-endpoint.

Fragments documentation

Update

Legacy publish 21.3

In rest V1 you could publish a record via media/:id/publish. This endpoint has been replaced with the property publish on the update endpoint.

Refer to https://mediahaven.atlassian.net/wiki/spaces/CS/pages/3046506546 for more information.

Specific fields BREAKING

In rest V1 it’s possible to update fields of a record via the media/:id/<field> endpoint. This endpoint is no longer available. As an alternative you can update the record by sending a POST-request to update the record with a partial sidecar.

Example:

 

1 2 3 4 5 6 7 8 POST https://integration.mediahaven.com/mediahaven-rest-api/v2/records/<id> { "Metadata": { "Descriptive": { "Title": "My new title" } } }

Fragments and children

Rest V1 provided endpoints to request fragments of a video/audio record and children of an ensemble. They are no longer available but can still be requested via the search-api.

Type

Rest v1

Rest v2 (search request)

Type

Rest v1

Rest v2 (search request)

fragments

/media/<recordid>/fragments

+(Internal.FragmentId:<recordId>*)

Ensemble (set)

/media/<recordId>/children

+(Structural.Sets.Set:<recordId>*)

Ensemble (collection)

/media/<recordId>/children

+(Structural.Collections.Collection:<recordId>*)

Ensemble (newspaper)

/media/<recordId>/children

+(Structural.Newspapers.Newspaper:<recordId>*)

Supported formats

Format

Rest v1

Rest v2

CREATE

GET

Format

Rest v1

Rest v2

CREATE

GET

 

application/xml (old style)

not supported

MHS

application/vnd.mediahaven.v2+xml

application/xml

MHS

application/vnd.mediahaven.v2+json

application/json

Dublin core

not supported

application/dc+xml

METS-MHS

not supported

application/mets+mhs+xml

Parent/child relations and inheritance 21.1

Parent/child via the relations attribute is deprecated and replaced with adoption. During adoption inheritance of values from the parent record is now possible.

Record Type & Status

Records can now have a type & status. Supported type and status is dependent on installation and configuration.

For legacy Mediahaven records, the following applies:

  • The record type is ‘Record’

  • The status is ‘New’ if located in an ingest space, or ‘Published’ if published.

Concurrent update of records 21.1

Updating the same record at the same time by 2 users will now throw a 409 Conflict error.

Searching

When executing a search the query sent is now strictly validated. Unknown fields, non-indexed fields or corrupt query syntax will throw a 400 bad request error.

Limits BREAKING

Number of records per page is now limited to 100.

Count endpoint

It’s now possible to get a count by sending a HEAD-request instead of GET-request → More info

Exports

The export API is rewritten but still supports the same features → Export request

Users

Current user BREAKING

The current user endpoint no longer returns all the properties of the user. Relations of the user are now sub endpoints of the current user endpoint

New features

Versioning

For metadata-only records it’s now possible to create versions of records. Each version starts with the status DRAFT. This object is not visible in the default search. To make it visible you will have to ACCEPT the draft or in case you don’t want to accept the DRAFT you can REJECT it. The current active version will have the status HEAD. Older version will have the status TAIL.

Profiles

Profiles can now be created and modified → documentation. Note that these profiles are not the same as the profiles in the old Content Uploader. These new profiles are available in MediaHaven 2.0.

Zip tree

Zip tree is a new combination mode for the export API that exports the record with all its children

Batches

A batch API was added to support updating a large amount of records with a single request. These batches are processed asynchronously.

Events 21.1

Record events can now be requested via the API

Difference between records 21.1

An API was added to view the difference between 2 records

Improved categories/ thesaurus 21.3

Categories are replaced with the new and improved thesaurus which is integrated in the search-engine so search queries are automatically enhanced with related terms.

Generating previews on demand 21.2

It’s now possible to (re)generate the preview of a file on demand https://integration.mediahaven.com/mediahaven-rest-api/v2/api-docs/index.html#mediahaven-rest-api-manual-batches-tasks