Overview

The InVID Rights Management API deals with the copyright aspects related with the reuse of User Generated Videos (UGV). Consequently, its use makes sense once a UGV has been verified and its reuse is intended.

An InVID User, usually a journalist, can perform the following actions through the InVID Rights Management API after authentication:

  1. Register a UGV using its URL.

  2. Get metadata about a registered UGV, focusing on its copyright status and uploader contact information. It also includes a default attribution message.

  3. Generate an invite message and link for an unregistered UGV uploader to register in the InVID Platform, and the accompanying reuse request.

  4. Generate a reuse request for a UGV uploader who already registered in the InVID Platform.

On the other hand, the UGV uploader can perform the following actions after confirming she or he is the content owner:

  1. Login into the InVID Platform using their social network credentials.

  2. Accept an invite and register in InVID using the credentials of the social network where the content was uploaded.

The underlying data model is presented in the class diagram included in the Domain Model Section.

InVID User (Journalist)

InVID users are users using the InVID platform for media verification and reuse, in most cases they will be journalists.

InVID User Authentication

In order to perform authenticated requests, any API user has to send, in the request’s header, a valid JWT authorization token.

However, the management of InVID Users authentication is done by the IdentityProvider module of the project. You can see its documentation in the following URL: https://identity-provider.invid.udl.cat/docs/index.html

UGV Registration

When an InVID User identifies a UGV she or he is interested in reusing, it can be registered using the API to retrieve available information from the corresponding social network about its rights status and uploader.

Currently, UGVs from YouTube and UGVs from Facebook can be registered.

InVID Users can register UGVs using a POST request or a PUT request to the InVID Rights Management API. The difference between both options appears just when the video is already registered in the platform, as detailed next.

UGV Registration using POST

If the posted URL corresponds to a video that is not registered yet, a new resource for the video is created with rights metadata retrieved from the UGV’s social network. The retrieved metada is included in the response.

If the video already exists in the platform, the response header includes the location of existing resource with the video metadata. No changes are produced so the video metadata is not updated, even if there are changes in the metadata stored by the UGV’s social network.

UGV Registration using PUT

The PUT request should be used over an existing video resource and point to its existing URL. In this case the video metadata will be updated with what is retrieved through the UGV’s social network API and the existing metadata overwritten. The response includes the updated metadata.

Examples

Here are some examples about how to register UGVs from the supported social networks using POST and PUT.

YouTube Video using POST
Request

Request Headers

Name Description

Content-Type

The Content-Type of the payload

Accept

The requested Content-Type of the response

Authorization

Should contain the string 'Bearer' plus the token obtained as a response to logging in

Request Fields

Path Type Description

url

String

URL of the YouTube video to be registered

Example Request

POST /youTubeVideos HTTP/1.1
Content-Type: application/json
Accept: application/hal+json
Authorization: Bearer INVID_VALID_TOKEN
Host: localhost:8080
Content-Length: 53

{"url":"https://www.youtube.com/watch?v=0MlCkZQjI2o"}
$ curl 'http://localhost:8080/youTubeVideos' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer INVID_VALID_TOKEN' -d '{"url":"https://www.youtube.com/watch?v=0MlCkZQjI2o"}'
Response

Response Headers

Name Description

Content-Type

The Content-Type of the payload

Location

URI of the new YouTube registered video

Response Fields

Path Type Description

id

String

The id of the registered YouTube video

title

String

The title of the registered YouTube video

url

String

URL of the registered YouTube video

thumbnail

String

A thumbnail of the registered YouTube video

publishDate

String

Date-time with a time-zone in the ISO-8601 calendar system, when the video was published

attribution

String

Attribution message for the video

description

String

Description of the registered YouTube video

registeredDate

String

Date and time of when the video was first submitted to the InVID Platform

lastUpdateDate

String

Date and time of the last time the video was updated

licensedContent

Boolean

Indicates whether the video represents licensed content, which means that the content was uploaded to a channel linked to a YouTube content partner and then claimed by that partner

license

String

Video’s license. Possible values are 'creativeCommons' and 'youtube'

blockedCountries

Null

A list with the countries where this video is blocked. In any other country, the video is allowed

allowedCountries

Null

A list with the countries where this video is allowed. In any other country, the video is blocked

contactInformation

Object

An object with the contact information extracted from the description of the video. The information is structured as follows: {"URL or email": "tags"} Where the tags specify the type of the contact information and are separated by commas

_links

Object

Links to related resources detailed in the next table

Response Links

Relation Description

self

The URI of the resource

youTubeVideo

The URI of the resource

user

The URI of the ExternalUser resource, a YouTubeChannel if the UGV is a YouTube video

reuseTerms

The URIs of the CopyrightStatements in which the UGV appears

reuseRequests

The URIs of the Reuse Policies Requests about this video

Example Response

HTTP/1.1 201 Created
Last-Modified: Tue, 07 Nov 2017 12:38:05 GMT
Location: http://localhost:8080/youTubeVideos/0MlCkZQjI2o
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1297

{
  "id" : "0MlCkZQjI2o",
  "title" : "SampleVideo 1280x720 50mb",
  "attribution" : "testInVIDGriho testInVIDGriho (2016, September 8). SampleVideo 1280x720 50mb. Retrieved from https://www.youtube.com/watch?v=0MlCkZQjI2o",
  "publishDate" : "2016-09-08T08:57:22Z",
  "url" : "https://www.youtube.com/watch?v=0MlCkZQjI2o",
  "thumbnail" : "https://i.ytimg.com/vi/0MlCkZQjI2o/hqdefault.jpg",
  "description" : "Descr: SampleVideo 1280x720 50mb",
  "contactInformation" : { },
  "registeredDate" : "2017-11-07T12:38:05.722Z",
  "lastUpdateDate" : "2017-11-07T12:38:05.722Z",
  "licensedContent" : false,
  "license" : "youtube",
  "blockedCountries" : null,
  "allowedCountries" : null,
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/youTubeVideos/0MlCkZQjI2o"
    },
    "youTubeVideo" : {
      "href" : "http://localhost:8080/youTubeVideos/0MlCkZQjI2o"
    },
    "user" : {
      "href" : "http://localhost:8080/youTubeVideos/0MlCkZQjI2o/user"
    },
    "submitters" : {
      "href" : "http://localhost:8080/youTubeVideos/0MlCkZQjI2o/submitters"
    },
    "reuseRequests" : {
      "href" : "http://localhost:8080/youTubeVideos/0MlCkZQjI2o/reuseRequests"
    },
    "reuseTerms" : {
      "href" : "http://localhost:8080/youTubeVideos/0MlCkZQjI2o/reuseTerms"
    }
  }
}
YouTube Video using PUT
Request

Request Headers

Name Description

Content-Type

The Content-Type of the payload

Accept

The requested Content-Type of the response

Authorization

Should contain the string 'Bearer' plus the token obtained as a response to logging in

Request Fields

Path Type Description

id

String

ID of the YouTube video to be registered

Example Request

PUT /youTubeVideos/Xb0P5t5NQWM HTTP/1.1
Content-Type: application/json
Accept: application/hal+json
Authorization: Bearer INVID_VALID_TOKEN
Host: localhost:8080
Content-Length: 20

{"id":"Xb0P5t5NQWM"}
$ curl 'http://localhost:8080/youTubeVideos/Xb0P5t5NQWM' -i -X PUT -H 'Content-Type: application/json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer INVID_VALID_TOKEN' -d '{"id":"Xb0P5t5NQWM"}'
Response

Response Headers

Name Description

Content-Type

The Content-Type of the payload

Location

URI of the new YouTube registered video

Response Fields

Path Type Description

id

String

The id of the registered YouTube video

title

String

The title of the registered YouTube video

url

String

URL of the registered YouTube video

thumbnail

String

A thumbnail of the registered YouTube video

publishDate

String

Date-time with a time-zone in the ISO-8601 calendar system, when the video was published

attribution

String

Attribution message for the video

description

String

Description of the registered YouTube video

registeredDate

String

Date and time of when the video was first submitted to the InVID Platform

lastUpdateDate

String

Date and time of the last time the video was updated

licensedContent

Boolean

Indicates whether the video represents licensed content, which means that the content was uploaded to a channel linked to a YouTube content partner and then claimed by that partner

license

String

Video’s license. Possible values are 'creativeCommons' and 'youtube'

blockedCountries

Null

A list with the countries where this video is blocked. In any other country, the video is allowed

allowedCountries

Null

A list with the countries where this video is allowed. In any other country, the video is blocked

contactInformation

Object

An object with the contact information extracted from the description of the video. The information is structured as follows: {"URL or email": "tags"} Where the tags specify the type of the contact information and are separated by commas

_links

Object

Links to related resources detailed in the next table

Response Links

Relation Description

self

The URI of the resource

youTubeVideo

The URI of the resource

user

The URI of the ExternalUser resource, a YouTubeChannel if the UGV is a YouTube video

reuseTerms

The URIs of the CopyrightStatements in which the UGV appears

reuseRequests

The URIs of the Reuse Policies Requests about this video

Example Response

HTTP/1.1 201 Created
Last-Modified: Tue, 07 Nov 2017 12:38:10 GMT
Location: http://localhost:8080/youTubeVideos/Xb0P5t5NQWM
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 2407

{
  "id" : "Xb0P5t5NQWM",
  "title" : "Golden Eagle Snatches Kid",
  "attribution" : "The MozaiK (2012, December 19). Golden Eagle Snatches Kid. Retrieved from https://www.youtube.com/watch?v=Xb0P5t5NQWM",
  "publishDate" : "2012-12-19T13:55:28Z",
  "url" : "https://www.youtube.com/watch?v=Xb0P5t5NQWM",
  "thumbnail" : "https://i.ytimg.com/vi/Xb0P5t5NQWM/hqdefault.jpg",
  "description" : "A golden eagle attempts top snatch a baby in Montreal!\n\nLIKE, COMMENT & SUBSCRIBE!\n\nThis video includes:\nGolden Eagle Snatches Baby\nGolden Eagle Snatches Kid\nGolden Eagle Takes Baby\nGolden Eagle Takes Kid\nBaby Taken by Golden Eagle\nKid Snatched by Golden Eagle\nBaby Snatched by Golden Eagle\nBird Snatches Kid\nBird Snatches Baby\nEagle Snatches Baby\n\nGolden Eagle Snatches Kid\nGolden Eagle Snatches Kid\nGolden Eagle Snatches Kid\n\nGolden Eagle Snatches Baby\nGolden Eagle Snatches Baby\nGolden Eagle Snatches Baby\n\nBaby Snatched by Golden Eagle\nBaby Snatched by Golden Eagle\nBaby Snatched by Golden Eagle\n\ngolden eagle snatches baby\ngolden eagle snatches kid\nkid picked up by golden eagle\ngolden eagle eats baby\ngolden eagle eats kid\nbird snatches baby\nbird snatches kid\ngolden eagle picks up kid\ngolden eagle picks up baby\ncrazy golden eagle\neagle picks up baby\neagle picks up kid\neagle snatches baby\nbaby snatches by eagle\nbig eagle snatches kid\nbig bird snatches kid\nbig eagle snatches baby\nhuge bird snatches kid\nmassive bird snatches kid\nmassive bird snatches baby\nhuge eagle snatches kid\nhuge eagle snatches baby",
  "contactInformation" : { },
  "registeredDate" : "2017-11-07T12:38:10.386Z",
  "lastUpdateDate" : "2017-11-07T12:38:10.386Z",
  "licensedContent" : true,
  "license" : "youtube",
  "blockedCountries" : null,
  "allowedCountries" : null,
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/youTubeVideos/Xb0P5t5NQWM"
    },
    "youTubeVideo" : {
      "href" : "http://localhost:8080/youTubeVideos/Xb0P5t5NQWM"
    },
    "reuseTerms" : {
      "href" : "http://localhost:8080/youTubeVideos/Xb0P5t5NQWM/reuseTerms"
    },
    "reuseRequests" : {
      "href" : "http://localhost:8080/youTubeVideos/Xb0P5t5NQWM/reuseRequests"
    },
    "submitters" : {
      "href" : "http://localhost:8080/youTubeVideos/Xb0P5t5NQWM/submitters"
    },
    "user" : {
      "href" : "http://localhost:8080/youTubeVideos/Xb0P5t5NQWM/user"
    }
  }
}
Facebook Video using POST
Request

Request Headers

Name Description

Content-Type

The Content-Type of the payload

Accept

The requested Content-Type of the response

Authorization

Should contain the string 'Bearer' plus the token obtained as a response to logging in

Request Fields

Path Type Description

url

String

URL of the Facebook video to be registered

Example Request

POST /facebookVideos HTTP/1.1
Content-Type: application/json
Accept: application/hal+json
Authorization: Bearer INVID_VALID_TOKEN
Host: localhost:8080
Content-Length: 74

{"url":"https://www.facebook.com/828215630661198/videos/828216780661083/"}
$ curl 'http://localhost:8080/facebookVideos' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer INVID_VALID_TOKEN' -d '{"url":"https://www.facebook.com/828215630661198/videos/828216780661083/"}'
Response

Response Headers

Name Description

Content-Type

The Content-Type of the payload

Location

URI of the new Facebook registered video

Response Fields

Path Type Description

id

String

The id of the registered Facebook video

title

String

The title of the registered Facebook video

url

String

URL of the registered Facebook video

thumbnail

String

A thumbnail of the registered YouTube video

publishDate

String

Date-time with a time-zone in the ISO-8601 calendar system, when the video was published

attribution

String

Attribution message for the video

description

String

Description of the registered Facebook video

registeredDate

String

Date and time of when the video was first submitted to the InVID Platform

lastUpdateDate

String

Date and time of the last time the video was updated

contactInformation

Object

An object with the contact information extracted from the description of the video. The information is structured as follows: {"URL or email": "tags"} Where the tags specify the type of the contact information and are separated by commas

_links

Object

Links to related resources detailed in the next table

Response Links

Relation Description

self

The URI of the resource

facebookVideo

The URI of the resource

user

The URI of the ExternalUser resource, a FacebookUser if the UGV is a Facebook video

reuseTerms

The URIs of the CopyrightStatements in which the UGV appears

reuseRequests

The URIs of the Reuse Policies Requests about this video

Example Response

HTTP/1.1 201 Created
Last-Modified: Tue, 07 Nov 2017 12:38:42 GMT
Location: http://localhost:8080/facebookVideos/828216780661083
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1440

{
  "id" : "828216780661083",
  "title" : "Test video",
  "attribution" : "Invid Test (2017, March 15). Test video. Retrieved from https://www.facebook.com/828215630661198/videos/828216780661083",
  "publishDate" : "2017-03-15T10:53:04Z",
  "url" : "https://www.facebook.com/828215630661198/videos/828216780661083",
  "thumbnail" : "https://scontent.xx.fbcdn.net/v/t15.0-10/p168x128/17308396_828218757327552_3501209729986723840_n.jpg?oh=f88ed91680f6b3b1914bc2d3f48cf556&oe=5A9E6C39",
  "description" : "This is a test video posted to Facebook Invid Test. Reuse it by sending an email to: testinvidgriho+video@gmail.com",
  "contactInformation" : {
    "testinvidgriho+video@gmail.com" : "email"
  },
  "registeredDate" : "2017-11-07T12:38:42.853Z",
  "lastUpdateDate" : "2017-11-07T12:38:42.853Z",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/facebookVideos/828216780661083"
    },
    "facebookVideo" : {
      "href" : "http://localhost:8080/facebookVideos/828216780661083"
    },
    "reuseTerms" : {
      "href" : "http://localhost:8080/facebookVideos/828216780661083/reuseTerms"
    },
    "reuseRequests" : {
      "href" : "http://localhost:8080/facebookVideos/828216780661083/reuseRequests"
    },
    "user" : {
      "href" : "http://localhost:8080/facebookVideos/828216780661083/user"
    },
    "submitters" : {
      "href" : "http://localhost:8080/facebookVideos/828216780661083/submitters"
    }
  }
}
Facebook Video using PUT
Request

Request Headers

Name Description

Content-Type

The Content-Type of the payload

Accept

The requested Content-Type of the response

Authorization

Should contain the string 'Bearer' plus the token obtained as a response to logging in

Request Fields

Path Type Description

id

String

ID of the Facebook video to be registered

Example Request

PUT /facebookVideos/828216780661083 HTTP/1.1
Content-Type: application/json
Accept: application/hal+json
Authorization: Bearer INVID_VALID_TOKEN
Host: localhost:8080
Content-Length: 24

{"id":"828216780661083"}
$ curl 'http://localhost:8080/facebookVideos/828216780661083' -i -X PUT -H 'Content-Type: application/json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer INVID_VALID_TOKEN' -d '{"id":"828216780661083"}'
Response

Response Headers

Name Description

Content-Type

The Content-Type of the payload

Location

URI of the new Facebook registered video

Response Fields

Path Type Description

id

String

The id of the registered Facebook video

title

String

The title of the registered Facebook video

url

String

URL of the registered Facebook video

thumbnail

String

A thumbnail of the registered YouTube video

publishDate

String

Date-time with a time-zone in the ISO-8601 calendar system, when the video was published

attribution

String

Attribution message for the video

description

String

Description of the registered Facebook video

registeredDate

String

Date and time of when the video was first submitted to the InVID Platform

lastUpdateDate

String

Date and time of the last time the video was updated

contactInformation

Object

An object with the contact information extracted from the description of the video. The information is structured as follows: {"URL or email": "tags"} Where the tags specify the type of the contact information and are separated by commas

_links

Object

Links to related resources detailed in the next table

Response Links

Relation Description

self

The URI of the resource

facebookVideo

The URI of the resource

user

The URI of the ExternalUser resource, a FacebookUser if the UGV is a Facebook video

reuseTerms

The URIs of the CopyrightStatements in which the UGV appears

reuseRequests

The URIs of the Reuse Policies Requests about this video

Example Response

HTTP/1.1 201 Created
Last-Modified: Tue, 07 Nov 2017 12:38:49 GMT
Location: http://localhost:8080/facebookVideos/828216780661083
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1440

{
  "id" : "828216780661083",
  "title" : "Test video",
  "attribution" : "Invid Test (2017, March 15). Test video. Retrieved from https://www.facebook.com/828215630661198/videos/828216780661083",
  "publishDate" : "2017-03-15T10:53:04Z",
  "url" : "https://www.facebook.com/828215630661198/videos/828216780661083",
  "thumbnail" : "https://scontent.xx.fbcdn.net/v/t15.0-10/p168x128/17308396_828218757327552_3501209729986723840_n.jpg?oh=f88ed91680f6b3b1914bc2d3f48cf556&oe=5A9E6C39",
  "description" : "This is a test video posted to Facebook Invid Test. Reuse it by sending an email to: testinvidgriho+video@gmail.com",
  "contactInformation" : {
    "testinvidgriho+video@gmail.com" : "email"
  },
  "registeredDate" : "2017-11-07T12:38:49.939Z",
  "lastUpdateDate" : "2017-11-07T12:38:49.939Z",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/facebookVideos/828216780661083"
    },
    "facebookVideo" : {
      "href" : "http://localhost:8080/facebookVideos/828216780661083"
    },
    "reuseRequests" : {
      "href" : "http://localhost:8080/facebookVideos/828216780661083/reuseRequests"
    },
    "submitters" : {
      "href" : "http://localhost:8080/facebookVideos/828216780661083/submitters"
    },
    "user" : {
      "href" : "http://localhost:8080/facebookVideos/828216780661083/user"
    },
    "reuseTerms" : {
      "href" : "http://localhost:8080/facebookVideos/828216780661083/reuseTerms"
    }
  }
}
Twitter Video using POST
Request

Request Headers

Name Description

Content-Type

The Content-Type of the payload

Accept

The requested Content-Type of the response

Authorization

Should contain the string 'Bearer' plus the token obtained as a response to logging in

Request Fields

Path Type Description

url

String

URL of the Twitter video to be registered

Example Request

POST /twitterVideos HTTP/1.1
Content-Type: application/json
Accept: application/hal+json
Authorization: Bearer INVID_VALID_TOKEN
Host: localhost:8080
Content-Length: 66

{"url":"https://twitter.com/invid_test/status/857179125076963329"}
$ curl 'http://localhost:8080/twitterVideos' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer INVID_VALID_TOKEN' -d '{"url":"https://twitter.com/invid_test/status/857179125076963329"}'
Response

Response Headers

Name Description

Content-Type

The Content-Type of the payload

Location

URI of the new Twitter registered video

Response Fields

Path Type Description

id

String

The id of the registered Twitter video

title

String

The title of the registered Twitter video

url

String

URL of the registered Twitter video

thumbnail

String

A thumbnail of the registered Twitter video

publishDate

String

Date-time with a time-zone in the ISO-8601 calendar system, when the video was published

attribution

String

Attribution message for the video

description

Null

Description of the registered Twitter video

registeredDate

String

Date and time of when the video was first submitted to the InVID Platform

lastUpdateDate

String

Date and time of the last time the video was updated

contactInformation

Object

An object with the contact information extracted from the description of the video and other fields. The information is structured as follows: {"URL or email": "tags"} Where the tags specify the type of the contact information and are separated by commas

_links

Object

Links to related resources detailed in the next table

Response Links

Relation Description

self

The URI of the resource

twitterVideo

The URI of the resource

user

The URI of the ExternalUser resource, a TwitterUser if the UGV is a Twitter video

reuseTerms

The URIs of the CopyrightStatements in which the UGV appears

reuseRequests

The URIs of the Reuse Policies Requests about this video

Example Response

HTTP/1.1 201 Created
Last-Modified: Tue, 07 Nov 2017 12:37:33 GMT
Location: http://localhost:8080/twitterVideos/857179125076963329
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1254

{
  "id" : "857179125076963329",
  "title" : "Campus UdL from GRIHO",
  "attribution" : "Test Invid (2017, April 26). Campus UdL from GRIHO. Retrieved from https://twitter.com/invid_test/status/857179125076963329/video/1",
  "publishDate" : "2017-04-26T10:26:43Z",
  "url" : "https://twitter.com/invid_test/status/857179125076963329/video/1",
  "thumbnail" : "http://pbs.twimg.com/ext_tw_video_thumb/857179018365370369/pu/img/TSzFWWUvUnaICKEm.jpg",
  "description" : null,
  "contactInformation" : { },
  "registeredDate" : "2017-11-07T12:37:33.686Z",
  "lastUpdateDate" : "2017-11-07T12:37:33.686Z",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/twitterVideos/857179125076963329"
    },
    "twitterVideo" : {
      "href" : "http://localhost:8080/twitterVideos/857179125076963329"
    },
    "submitters" : {
      "href" : "http://localhost:8080/twitterVideos/857179125076963329/submitters"
    },
    "user" : {
      "href" : "http://localhost:8080/twitterVideos/857179125076963329/user"
    },
    "reuseTerms" : {
      "href" : "http://localhost:8080/twitterVideos/857179125076963329/reuseTerms"
    },
    "reuseRequests" : {
      "href" : "http://localhost:8080/twitterVideos/857179125076963329/reuseRequests"
    }
  }
}
Twitter Video using PUT
Request

Request Headers

Name Description

Content-Type

The Content-Type of the payload

Accept

The requested Content-Type of the response

Authorization

Should contain the string 'Bearer' plus the token obtained as a response to logging in

Request Fields

Path Type Description

id

String

ID of the Twitter video to be registered

Example Request

PUT /twitterVideos/857179125076963329 HTTP/1.1
Content-Type: application/json
Accept: application/hal+json
Authorization: Bearer INVID_VALID_TOKEN
Host: localhost:8080
Content-Length: 27

{"id":"857179125076963329"}
$ curl 'http://localhost:8080/twitterVideos/857179125076963329' -i -X PUT -H 'Content-Type: application/json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer INVID_VALID_TOKEN' -d '{"id":"857179125076963329"}'
Response

Response Headers

Name Description

Content-Type

The Content-Type of the payload

Location

URI of the new Twitter registered video

Response Fields

Path Type Description

id

String

The id of the registered Twitter video

title

String

The title of the registered Twitter video

url

String

URL of the registered Twitter video

thumbnail

String

A thumbnail of the registered Twitter video

publishDate

String

Date-time with a time-zone in the ISO-8601 calendar system, when the video was published

attribution

String

Attribution message for the video

description

Null

Description of the registered Twitter video

registeredDate

String

Date and time of when the video was first submitted to the InVID Platform

lastUpdateDate

String

Date and time of the last time the video was updated

contactInformation

Object

An object with the contact information extracted from the description of the video. The information is structured as follows: {"URL or email": "tags"} Where the tags specify the type of the contact information and are separated by commas

_links

Object

Links to related resources detailed in the next table

Response Links

Relation Description

self

The URI of the resource

twitterVideo

The URI of the resource

user

The URI of the ExternalUser resource, a TwitterUser if the UGV is a Twitter video

reuseTerms

The URIs of the CopyrightStatements in which the UGV appears

reuseRequests

The URIs of the Reuse Policies Requests about this video

Example Response

HTTP/1.1 201 Created
Last-Modified: Tue, 07 Nov 2017 12:38:35 GMT
Location: http://localhost:8080/twitterVideos/857179125076963329
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1254

{
  "id" : "857179125076963329",
  "title" : "Campus UdL from GRIHO",
  "attribution" : "Test Invid (2017, April 26). Campus UdL from GRIHO. Retrieved from https://twitter.com/invid_test/status/857179125076963329/video/1",
  "publishDate" : "2017-04-26T10:26:43Z",
  "url" : "https://twitter.com/invid_test/status/857179125076963329/video/1",
  "thumbnail" : "http://pbs.twimg.com/ext_tw_video_thumb/857179018365370369/pu/img/TSzFWWUvUnaICKEm.jpg",
  "description" : null,
  "contactInformation" : { },
  "registeredDate" : "2017-11-07T12:38:35.386Z",
  "lastUpdateDate" : "2017-11-07T12:38:35.386Z",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/twitterVideos/857179125076963329"
    },
    "twitterVideo" : {
      "href" : "http://localhost:8080/twitterVideos/857179125076963329"
    },
    "user" : {
      "href" : "http://localhost:8080/twitterVideos/857179125076963329/user"
    },
    "reuseTerms" : {
      "href" : "http://localhost:8080/twitterVideos/857179125076963329/reuseTerms"
    },
    "submitters" : {
      "href" : "http://localhost:8080/twitterVideos/857179125076963329/submitters"
    },
    "reuseRequests" : {
      "href" : "http://localhost:8080/twitterVideos/857179125076963329/reuseRequests"
    }
  }
}
Contact Information tags

The "contactInformation" field holds any link or email which could be used to contact the user. These information is extracted from "description" fields of the different social accounts.

We extract any URL found and the tag format is:

  • other,url

If the URL is from a social network account, we tag it as follows:

  • social-network,<Facebook, Twitter, Youtube, Instagram>,url: It is an URL

Additionally, YouTube channels have an "about" page holding links to other social accounts or websites. Each of these links have a "title", so the format of the Contact Information tag is:

  • link,<title>

Retrieve UGV Rights Metadata

With a GET request to a previously registered UGV URL the available metadata for that UGV is retrieved. This includes the generated attribution message plus all the available metadata retrieved from the YouTube API.

This is the metadata available when the UGV was registered using a POST request, or that available the last time a PUT request was performed to update it.

Request

Request Headers

Name Description

Accept

The requested Content-Type of the response

Path Parameters

Table 1. /uGVs/{UGV Identifier}
Parameter Description

UGV Identifier

The identifier of the UGV

Example Request

GET /uGVs/Xb0P5t5NQWM HTTP/1.1
Accept: application/hal+json
Host: localhost:8080
$ curl 'http://localhost:8080/uGVs/Xb0P5t5NQWM' -i -H 'Accept: application/hal+json'

Response

Response Headers

Name Description

Content-Type

The Content-Type of the payload

Response Fields

Path Type Description

id

String

The id of the registered YouTube video

title

String

The title of the registered YouTube video

url

String

URL of the registered YouTube video

thumbnail

String

A thumbnail of the registered YouTube video

publishDate

String

Date-time with a time-zone in the ISO-8601 calendar system, when the video was published

attribution

String

Attribution message for the video

description

String

Description of the registered YouTube video

registeredDate

String

Date and time of when the video was first submitted to the InVID Platform

lastUpdateDate

String

Date and time of the last time the video was updated

licensedContent

Boolean

Indicates whether the video represents licensed content, which means that the content was uploaded to a channel linked to a YouTube content partner and then claimed by that partner

license

String

Video’s license. Possible values are 'creativeCommons' and 'youtube'

blockedCountries

Array

A list with the countries where this video is blocked. In any other country, the video is allowed

allowedCountries

Array

A list with the countries where this video is allowed. In any other country, the video is blocked

contactInformation

Object

An object with the contact information extracted from the description of the video. The information is structured as follows: {"URL or email": "tags"} Where the tags specify the type of the contact information and are separated by commas

_links

Object

Links to related resources detailed in the next table

Response Links

Relation Description

self

The URI of the resource

youTubeVideo

The URI of the resource

user

The URI of the ExternalUser resource, a YouTubeChannel if the UGV is a YouTube video

reuseTerms

The URIs of the CopyrightStatements in which the UGV appears

reuseRequests

The URIs of the Reuse Policies Requests about this video

Example Response

HTTP/1.1 200 OK
Last-Modified: Tue, 07 Nov 2017 12:38:18 GMT
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 2405

{
  "id" : "Xb0P5t5NQWM",
  "title" : "Golden Eagle Snatches Kid",
  "attribution" : "The MozaiK (2012, December 19). Golden Eagle Snatches Kid. Retrieved from https://www.youtube.com/watch?v=Xb0P5t5NQWM",
  "publishDate" : "2012-12-19T13:55:28Z",
  "url" : "https://www.youtube.com/watch?v=Xb0P5t5NQWM",
  "thumbnail" : "https://i.ytimg.com/vi/Xb0P5t5NQWM/hqdefault.jpg",
  "description" : "A golden eagle attempts top snatch a baby in Montreal!\n\nLIKE, COMMENT & SUBSCRIBE!\n\nThis video includes:\nGolden Eagle Snatches Baby\nGolden Eagle Snatches Kid\nGolden Eagle Takes Baby\nGolden Eagle Takes Kid\nBaby Taken by Golden Eagle\nKid Snatched by Golden Eagle\nBaby Snatched by Golden Eagle\nBird Snatches Kid\nBird Snatches Baby\nEagle Snatches Baby\n\nGolden Eagle Snatches Kid\nGolden Eagle Snatches Kid\nGolden Eagle Snatches Kid\n\nGolden Eagle Snatches Baby\nGolden Eagle Snatches Baby\nGolden Eagle Snatches Baby\n\nBaby Snatched by Golden Eagle\nBaby Snatched by Golden Eagle\nBaby Snatched by Golden Eagle\n\ngolden eagle snatches baby\ngolden eagle snatches kid\nkid picked up by golden eagle\ngolden eagle eats baby\ngolden eagle eats kid\nbird snatches baby\nbird snatches kid\ngolden eagle picks up kid\ngolden eagle picks up baby\ncrazy golden eagle\neagle picks up baby\neagle picks up kid\neagle snatches baby\nbaby snatches by eagle\nbig eagle snatches kid\nbig bird snatches kid\nbig eagle snatches baby\nhuge bird snatches kid\nmassive bird snatches kid\nmassive bird snatches baby\nhuge eagle snatches kid\nhuge eagle snatches baby",
  "contactInformation" : { },
  "registeredDate" : "2017-11-07T12:38:18.282Z",
  "lastUpdateDate" : "2017-11-07T12:38:18.282Z",
  "licensedContent" : true,
  "license" : "youtube",
  "blockedCountries" : [ ],
  "allowedCountries" : [ ],
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/youTubeVideos/Xb0P5t5NQWM"
    },
    "youTubeVideo" : {
      "href" : "http://localhost:8080/youTubeVideos/Xb0P5t5NQWM"
    },
    "submitters" : {
      "href" : "http://localhost:8080/youTubeVideos/Xb0P5t5NQWM/submitters"
    },
    "user" : {
      "href" : "http://localhost:8080/youTubeVideos/Xb0P5t5NQWM/user"
    },
    "reuseTerms" : {
      "href" : "http://localhost:8080/youTubeVideos/Xb0P5t5NQWM/reuseTerms"
    },
    "reuseRequests" : {
      "href" : "http://localhost:8080/youTubeVideos/Xb0P5t5NQWM/reuseRequests"
    }
  }
}

Reuse Term

A Reuse Term before registering a Reuse Request, it determines what the Reuse Request is asking for.

Only InVID Users can generate reuse requests. A POST request is used and it should specify URI of the UGV.

Request

Request Headers

Name Description

Content-Type

The Content-Type of the payload

Accept

The requested Content-Type of the response

Authorization

JWT Authoritzation, HTTPS recommended

Request Fields

Path Type Description

action

String

Reuse action(s) the Reuse Term refers to, like 'publish' or 'copy'

who

Array

URI(s) of the User(s) or Organization(s) to perform the reuse action(s)

what

Array

URI(s) of the content to which the Reuse Term applies

when

String

Date-time with a time-zone in the ISO-8601 calendar system, from which the Reuse Term applies

duration

String

Date-based amount of time in the ISO-8601 calendar system, after 'when' for which the Reuse Term applies

where

String

Countries where the Reuse Term applies

with

String

Tool or instrument with which the Reuse Term applies

why

String

Reason for requesting the Reuse Term

how

String

How the content will be reused

preconditions

String

Preconditions to fulfil before the Reuse Term applies

postconditions

String

Postconditions to fulfil after reusing the content

Example Request

POST /reuseTerms HTTP/1.1
Content-Type: application/json
Accept: application/hal+json
Authorization: Bearer INVID_VALID_TOKEN
Host: localhost:8080
Content-Length: 346

{ "action": "publish","who": ["/organizations/5f0b2074-0465-4dfb-8ad3-53317cc00a7d"],"what": ["/uGVs/Xb0P5t5NQWM"],"when": "2017-05-01T00:00Z","duration": "P3M","where": "Spain","with": "Tablet","why": "To broadcast it on TV news","how": "Broadcast on TV","preconditions": "After having paid the agreed fee","postconditions": "No Post Condition"}
$ curl 'http://localhost:8080/reuseTerms' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer INVID_VALID_TOKEN' -d '{ "action": "publish","who": ["/organizations/5f0b2074-0465-4dfb-8ad3-53317cc00a7d"],"what": ["/uGVs/Xb0P5t5NQWM"],"when": "2017-05-01T00:00Z","duration": "P3M","where": "Spain","with": "Tablet","why": "To broadcast it on TV news","how": "Broadcast on TV","preconditions": "After having paid the agreed fee","postconditions": "No Post Condition"}'

Response

Response Headers

Name Description

Content-Type

The Content-Type of the payload

Location

URI of the new Reuse Term

Response Fields

Path Type Description

id

String

The id of the Reuse Term

action

String

Reuse action(s) the Reuse Term refers to, like 'publish' or 'copy'

when

String

Date-time with a time-zone in the ISO-8601 calendar system, from which the Reuse Term applies

duration

String

Date-based amount of time in the ISO-8601 calendar system, after 'when' for which the Reuse Term applies

where

String

Countries where the Reuse Term applies

with

String

Tool or instrument with which the Reuse Term applies

why

String

Reason for requesting the Reuse Term

how

String

How the content will be reused

preconditions

String

Preconditions to fulfil before the Reuse Term applies

postconditions

String

Postconditions to fulfil after reusing the content

_links

Object

Links to related resources detailed in the next table

Response Links

Relation Description

self

The URI of the resource

reuseTerm

The URI of the resource

who

URI(s) of the User(s) or Organization(s) to perform the reuse action(s)

what

URI(s) of the content to which the Reuse Term applies

partOf

The URI of the Reuse Request in which this Reuse Term is applied

Example Response

HTTP/1.1 201 Created
Location: http://localhost:8080/reuseTerms/aae26f76-b24d-4731-a430-23b9805f8b49
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 927

{
  "id" : "aae26f76-b24d-4731-a430-23b9805f8b49",
  "action" : "publish",
  "when" : "2017-05-01T00:00:00Z",
  "duration" : "P3M",
  "where" : "Spain",
  "with" : "Tablet",
  "why" : "To broadcast it on TV news",
  "how" : "Broadcast on TV",
  "preconditions" : "After having paid the agreed fee",
  "postconditions" : "No Post Condition",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/reuseTerms/aae26f76-b24d-4731-a430-23b9805f8b49"
    },
    "reuseTerm" : {
      "href" : "http://localhost:8080/reuseTerms/aae26f76-b24d-4731-a430-23b9805f8b49"
    },
    "who" : {
      "href" : "http://localhost:8080/reuseTerms/aae26f76-b24d-4731-a430-23b9805f8b49/who"
    },
    "what" : {
      "href" : "http://localhost:8080/reuseTerms/aae26f76-b24d-4731-a430-23b9805f8b49/what"
    },
    "partOf" : {
      "href" : "http://localhost:8080/reuseTerms/aae26f76-b24d-4731-a430-23b9805f8b49/partOf"
    }
  }
}

Reuse Policy

A Reuse Policy is created by someone of an Organization members in order to act as the default pattern for the members of the organization when they are going to register Reuse Terms for a Reuse Request. Additionally, a Reuse Policy can also be created by any User in order to set up a default pattern for himself.

Both InVID Users and Content Owners can generate reuse requests. A POST request is used and it should specify URI of the UGV.

Request

Request Headers

Name Description

Content-Type

The Content-Type of the payload

Accept

The requested Content-Type of the response

Authorization

JWT Authoritzation, HTTPS recommended

Request Fields

Path Type Description

action

String

Reuse action(s) the Reuse Policy refers to, like 'publish' or 'copy'

who

Array

URI(s) of the User(s) or Organization(s) to perform the reuse action(s)

what

Array

URI(s) of the content to which the Reuse Policy applies

when

String

Date-time with a time-zone in the ISO-8601 calendar system, from which the Reuse Policy applies

duration

String

Date-based amount of time in the ISO-8601 calendar system, after 'when' for which the Reuse Policy applies

where

String

Countries where the Reuse Policy applies

with

String

Tool or instrument with which the Reuse Policy applies

why

String

Reason for requesting the Reuse Policy

how

String

How the content will be reused

preconditions

String

Preconditions to fulfil before the Reuse Policy applies

postconditions

String

Postconditions to fulfil after reusing the content

defaultFor

String

The URI of the Agent of whom this Reuse Policy is default

Example Request

POST /reusePolicies HTTP/1.1
Content-Type: application/json
Accept: application/hal+json
Authorization: Bearer INVID_VALID_TOKEN
Host: localhost:8080
Content-Length: 413

{ "action": "publish","who": ["/organizations/7f418629-11a8-4d92-b71d-3e63aa0a9848"],"what": ["/uGVs/Xb0P5t5NQWM"],"when": "2017-05-01T00:00Z","duration": "P3M","where": "Spain","with": "Tablet","why": "To broadcast it on TV news","how": "Broadcast on TV","preconditions": "After having paid the agreed fee","postconditions": "No Post Condition","defaultFor": "/organization/7f418629-11a8-4d92-b71d-3e63aa0a9848"}
$ curl 'http://localhost:8080/reusePolicies' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer INVID_VALID_TOKEN' -d '{ "action": "publish","who": ["/organizations/7f418629-11a8-4d92-b71d-3e63aa0a9848"],"what": ["/uGVs/Xb0P5t5NQWM"],"when": "2017-05-01T00:00Z","duration": "P3M","where": "Spain","with": "Tablet","why": "To broadcast it on TV news","how": "Broadcast on TV","preconditions": "After having paid the agreed fee","postconditions": "No Post Condition","defaultFor": "/organization/7f418629-11a8-4d92-b71d-3e63aa0a9848"}'

Response

Response Headers

Name Description

Content-Type

The Content-Type of the payload

Location

URI of the new Reuse Policy registered

Response Fields

Path Type Description

id

String

The id of the Reuse Policy

action

String

Reuse action(s) the Reuse Policy refers to, like 'publish' or 'copy'

when

String

Date-time with a time-zone in the ISO-8601 calendar system, from which the Reuse Policy applies

duration

String

Date-based amount of time in the ISO-8601 calendar system, after 'when' for which the Reuse Policy applies

where

String

Countries where the Reuse Policy applies

with

String

Tool or instrument with which the Reuse Policy applies

why

String

Reason for requesting the Reuse Policy

how

String

How the content will be reused

preconditions

String

Preconditions to fulfil before the Reuse Policy applies

postconditions

String

Postconditions to fulfil after reusing the content

_links

Object

Links to related resources detailed in the next table

Response Links

Relation Description

self

The URI of the resource

reusePolicy

The URI of the resource

who

URI(s) of the User(s) or Organization(s) to perform the reuse action(s)

what

URI(s) of the content to which the Reuse Policy applies

definedBy

The URI of the User who has created this Reuse Policy

defaultFor

The URI of the Agent of whom this Reuse Policy is default

Example Response

HTTP/1.1 201 Created
Location: http://localhost:8080/reusePolicies/b0e9cefa-1f3e-465b-a1cb-7eee6ce375b0
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1079

{
  "id" : "b0e9cefa-1f3e-465b-a1cb-7eee6ce375b0",
  "action" : "publish",
  "when" : "2017-05-01T00:00:00Z",
  "duration" : "P3M",
  "where" : "Spain",
  "with" : "Tablet",
  "why" : "To broadcast it on TV news",
  "how" : "Broadcast on TV",
  "preconditions" : "After having paid the agreed fee",
  "postconditions" : "No Post Condition",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/reusePolicies/b0e9cefa-1f3e-465b-a1cb-7eee6ce375b0"
    },
    "reusePolicy" : {
      "href" : "http://localhost:8080/reusePolicies/b0e9cefa-1f3e-465b-a1cb-7eee6ce375b0"
    },
    "what" : {
      "href" : "http://localhost:8080/reusePolicies/b0e9cefa-1f3e-465b-a1cb-7eee6ce375b0/what"
    },
    "who" : {
      "href" : "http://localhost:8080/reusePolicies/b0e9cefa-1f3e-465b-a1cb-7eee6ce375b0/who"
    },
    "defaultFor" : {
      "href" : "http://localhost:8080/reusePolicies/b0e9cefa-1f3e-465b-a1cb-7eee6ce375b0/defaultFor"
    },
    "definedBy" : {
      "href" : "http://localhost:8080/reusePolicies/b0e9cefa-1f3e-465b-a1cb-7eee6ce375b0/definedBy"
    }
  }
}

Reuse Request

Before creating a Reuse Request, a Reuse Term must have been created. On it we should have defined the terms we are asking for through the Reuse Request.

A Reuse Request should be created to request the uploader of a UGV permission to reuse it. The objective is that, once registered and after confirming she or he is the content owner, who shot the video, they can state their agreement about the reuse request or negotiate the reuse conditions.

If the uploader of the UGV, whose reuse is intended, is not registered in the InVID Platform, an InVID Invite will be created. The invite allows the uploader of UGV to join the InVID Platform and includes a default invite message. The invite can be retrieved following the inVIDInvite link in created the Reuse Response, for instance:

http://rights-api.invid.udl.cat/reuseRequests/{reuse-request-id}/inVIDInvite

Otherwise, if the uploader is already registered, the invite is not generated, just the Reuse Request.

Only InVID Users can generate reuse requests. A POST request is used and it should specify URI of the UGV.

Request

Request Headers

Name Description

Content-Type

The Content-Type of the payload

Accept

The requested Content-Type of the response

Authorization

JWT Authoritzation, HTTPS recommended

Request Fields

Path Type Description

aboutVideo

String

The URI to the requested UGV

inviteLinkBase

String

The location of the client application to accept invites

requestLinkBase

String

The location of the client application to accept request

terms

Array

The URI to the reuse terms requesting on this Reuse Request

Example Request

POST /reuseRequests HTTP/1.1
Content-Type: application/json
Accept: application/hal+json
Authorization: Bearer INVID_VALID_TOKEN
Host: localhost:8080
Content-Length: 216

{"aboutVideo": "/uGVs/uXjFGmAMwpc","terms": ["/reuseTerms/aca45ad7-a1a7-4b27-a67e-4f8bdc861558"],"inviteLinkBase": "http://rights.invid.udl.cat/#/invite/","requestLinkBase": "http://rights.invid.udl.cat/#/request/" }
$ curl 'http://localhost:8080/reuseRequests' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer INVID_VALID_TOKEN' -d '{"aboutVideo": "/uGVs/uXjFGmAMwpc","terms": ["/reuseTerms/aca45ad7-a1a7-4b27-a67e-4f8bdc861558"],"inviteLinkBase": "http://rights.invid.udl.cat/#/invite/","requestLinkBase": "http://rights.invid.udl.cat/#/request/" }'

Response

Response Headers

Name Description

Content-Type

The Content-Type of the payload

Location

URI of the new Reuse Policy Request registered

Response Fields

Path Type Description

id

String

The id of the Reuse Policy Request

dateTime

String

The date-time with a time-zone in the ISO-8601 calendar system, when this reuse request was created

status

String

The status of the Reuse Policy Request (NEW, VIEWED, REJECTED or ACCEPTED)

statusChanged

Boolean

Indicates if the status has changed from the last time the journalist saw it

lastStatusChange

String

Date-time with a time-zone in the ISO-8601 calendar system, indicating the last time the status of this request changed

_links

Object

Links to related resources detailed in the next table

Response Links

Relation Description

self

The URI of the resource

reuseRequest

The URI of the resource

aboutVideo

The URI to the requested UGV

createdBy

The URI to the InVIDUser owner

inVIDInvite

The URI to the related InVIDInvite

agreedBy

The URI to the agreement indicating that this Reuse Request is accepted

terms

The URI to the reuse terms requesting on this Reuse Request

Example Response

HTTP/1.1 201 Created
Location: http://localhost:8080/reuseRequests/f8021f25-9c22-4d28-a738-7312eb9d3f7d
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1074

{
  "id" : "f8021f25-9c22-4d28-a738-7312eb9d3f7d",
  "dateTime" : "2017-11-07T12:37:38.533Z",
  "status" : "NEW",
  "statusChanged" : false,
  "lastStatusChange" : "2017-11-07T12:37:38.415Z",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/reuseRequests/f8021f25-9c22-4d28-a738-7312eb9d3f7d"
    },
    "reuseRequest" : {
      "href" : "http://localhost:8080/reuseRequests/f8021f25-9c22-4d28-a738-7312eb9d3f7d"
    },
    "terms" : {
      "href" : "http://localhost:8080/reuseRequests/f8021f25-9c22-4d28-a738-7312eb9d3f7d/terms"
    },
    "inVIDInvite" : {
      "href" : "http://localhost:8080/reuseRequests/f8021f25-9c22-4d28-a738-7312eb9d3f7d/inVIDInvite"
    },
    "aboutVideo" : {
      "href" : "http://localhost:8080/reuseRequests/f8021f25-9c22-4d28-a738-7312eb9d3f7d/aboutVideo"
    },
    "createdBy" : {
      "href" : "http://localhost:8080/reuseRequests/f8021f25-9c22-4d28-a738-7312eb9d3f7d/createdBy"
    },
    "agreedBy" : {
      "href" : "http://localhost:8080/reuseRequests/f8021f25-9c22-4d28-a738-7312eb9d3f7d/agreedBy"
    }
  }
}

Invite a UGV Content Uploader

An InVID Invite is created to invite the uploader of UGV to join the InVID Platform.

It is automatically created when registering a Reuse Request for a UGV of which its uploader, identified by its profile in the social network where the UGV was uploaded, has not joined the InVID Platform yet.

It is not possible to create an InVID Invite directly. The only available operation is a GET.

Request

Request Headers

Name Description

Accept

The requested Content-Type of the response

Example Request

GET /inVIDInvites/b4ccdaf6-101b-430c-bdef-56b30cff8d2e HTTP/1.1
Accept: application/hal+json
Host: localhost:8080
$ curl 'http://localhost:8080/inVIDInvites/b4ccdaf6-101b-430c-bdef-56b30cff8d2e' -i -H 'Accept: application/hal+json'

Response

Response Headers

Name Description

Content-Type

The Content-Type of the payload

Response Fields

Path Type Description

id

String

The generated identifier for the InVID Invite

inviteMessage

Null

Proposed template for the invite message

_links

Object

Links to related resources detailed in the next table

Response Links

Relation Description

self

The URI of the resource

inVIDInvite

The URI of the resource

acceptedBy

The URI of the InVIDUser created from this invite (initially null)

invitedUser

The URI of the invited external user

reuseRequest

The URI of the ReuseRequest for which has been created the invite

Example Response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 715

{
  "id" : "b4ccdaf6-101b-430c-bdef-56b30cff8d2e",
  "inviteMessage" : null,
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/inVIDInvites/b4ccdaf6-101b-430c-bdef-56b30cff8d2e"
    },
    "inVIDInvite" : {
      "href" : "http://localhost:8080/inVIDInvites/b4ccdaf6-101b-430c-bdef-56b30cff8d2e"
    },
    "invitedUser" : {
      "href" : "http://localhost:8080/inVIDInvites/b4ccdaf6-101b-430c-bdef-56b30cff8d2e/invitedUser"
    },
    "reuseRequest" : {
      "href" : "http://localhost:8080/inVIDInvites/b4ccdaf6-101b-430c-bdef-56b30cff8d2e/reuseRequest"
    },
    "acceptedBy" : {
      "href" : "http://localhost:8080/inVIDInvites/b4ccdaf6-101b-430c-bdef-56b30cff8d2e/acceptedBy"
    }
  }
}

Content Owner

Content owners correspond to social network users whose content, uploaded to these social networks, InVID Platform users intend to reuse. These uploaders are invited to the platform to negotiate the reuse of their content and to confirm they are the content owners, the person who shot the UGV.

The way to log into the platform for this kind of users is using their social network account. This way it is possible to verify they are the uploaders of the UGV. They can login directly using their social network credentials or through an invite generated by an InVID User for a particular UGV they uploaded.

Authentication

Google Authentication for YouTube Users

For authentication as a YouTube user, Google credentials should be used. Concretely, OAuth 2 authentication should be used to obtain an OAuth 2 Google ID Token. This token is then posted to /login as the value for the field "googleIdToken" in the JSON payload as detailed in the Request subsection below.

To obtain a valid ID Token, please, follow the instructions at: http://www.invid-project.eu/wiki/doku.php?id=wp4#invid_rights_management_services

Request

Request Headers

Name Description

Content-Type

The Content-Type of the payload

Accept

The requested Content-Type of the response

Request Fields

Path Type Description

googleIdToken

String

A valid id token from Google API

Example Request

POST /login HTTP/1.1
Content-Type: application/json
Accept: application/hal+json
Host: localhost:8080
Content-Length: 33

{"googleIdToken":"eyJ0eXAiOiJKV"}
$ curl 'http://localhost:8080/login' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/hal+json' -d '{"googleIdToken":"eyJ0eXAiOiJKV"}'
Response

Response Headers

Name Description

Content-Type

The Content-Type of the payload

Response Fields

Path Type Description

id

String

The id of the logged user

username

String

The username of the logged user

email

String

The email of the logged user

authorities

Array

The roles of the logged user

Example Response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 139

{"id":"e6309144-60e3-45c0-8231-8fffa4e8fd30","email":"user@gmail.com","username":"user","authorities":[{"authority":"ROLE_CONTENT_OWNER"}]}

Facebook Authentication

For authentication as a Facebook user, Facebook credentials should be used. Concretely, OAuth 2 authentication should be used to obtain a Facebook User Access Token. This token can be obtaine using the Facebook tool: https://developers.facebook.com/tools/explorer/

Please, select the option "Get User Access Token" and directly, at the bottom, click "Get Access Token", no need to change anything else.

This token is then posted to /login as the value for the field "facebookAccessToken" in the JSON payload as detailed in the Request subsection below.

Request

Request Headers

Name Description

Content-Type

The Content-Type of the payload

Accept

The requested Content-Type of the response

Request Fields

Path Type Description

facebookAccessToken

String

A valid access token from Facebook OAuth2 API

Example Request

POST /login HTTP/1.1
Content-Type: application/json
Accept: application/hal+json
Host: localhost:8080
Content-Length: 40

{"facebookAccessToken":"2.h1MTNeLqcLqw"}
$ curl 'http://localhost:8080/login' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/hal+json' -d '{"facebookAccessToken":"2.h1MTNeLqcLqw"}'
Response

Response Headers

Name Description

Content-Type

The Content-Type of the payload

Response Fields

Path Type Description

id

String

The id of the logged user

username

String

The username of the logged user

email

String

The email of the logged user

authorities

Array

The roles of the logged user

Example Response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 142

{"id":"d682c895-1d50-443d-9892-00b9c26d0a2e","email":"user@facebook.com","username":"user","authorities":[{"authority":"ROLE_CONTENT_OWNER"}]}

Twitter Authentication

For authentication as a Twitter user, Twitter credentials should be used. Concretely, OAuth authentication should be used to obtain an OAuth Access Token. This token is then posted to /login as the value for the field "twitterAccessToken" in the JSON payload as detailed in the Request subsection below.

Since Twitter only supports OAuth 1, we have integrated this funcionality into the InVID Identity Provider available at: https://identity-provider.invid.udl.cat

The documentation for this feature of the Identity Provider is available from: https://identity-provider.invid.udl.cat/docs/index.html#twitter-sign-in

Request

Request Headers

Name Description

Content-Type

The Content-Type of the payload

Accept

The requested Content-Type of the response

Request Fields

Path Type Description

twitterAccessToken

String

A valid access token from Twitter OAuth API

Example Request

POST /login HTTP/1.1
Content-Type: application/json
Accept: application/hal+json
Host: localhost:8080
Content-Length: 38

{"twitterAccessToken":"NPcudxy0yU5T3"}
$ curl 'http://localhost:8080/login' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/hal+json' -d '{"twitterAccessToken":"NPcudxy0yU5T3"}'
Response

Response Headers

Name Description

Content-Type

The Content-Type of the payload

Response Fields

Path Type Description

id

String

The id of the logged user

username

String

The username of the logged user

email

String

The email of the logged user

authorities

Array

The roles of the logged user

Example Response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 141

{"id":"735bd96e-af44-4023-b098-043667270aca","email":"user@twitter.com","username":"user","authorities":[{"authority":"ROLE_CONTENT_OWNER"}]}

Social account verification

In order to connect all social accounts in a single Content Owner user, we provide a way of verifying them. When a Content Owner user verifies a social account, two things happens:

  • The user can now login to the InVID Rights Platform (as Content Owner) using anyone of his connected social accounts.

  • The platform knows that the Content Owner owns a given social account, so when a new video from this account is submitted to the platform, we will automatically contact him.

To verify a Social account, all you have to do is an authenticated login with the Social account to verify.

Google verification

Request

Example Request

POST /verify HTTP/1.1
Content-Type: application/json
Accept: application/hal+json
Authorization: Bearer eyJ0eXAiOiJKV
Host: localhost:8080
Content-Length: 33

{"googleIdToken":"eyJ0eXAiOiJKV"}
$ curl 'http://localhost:8080/verify' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer eyJ0eXAiOiJKV' -d '{"googleIdToken":"eyJ0eXAiOiJKV"}'
Response

Example Response

HTTP/1.1 200 OK

YouTube verification

Request

Request Headers

Name Description

Content-Type

The Content-Type of the payload

Accept

The requested Content-Type of the response

Authorization

Should contain the string 'Bearer' plus the token obtained from a Social Network login

Request Fields

Path Type Description

googleAccessToken

String

A valid access token from Google OAuth2 API

Example Request

POST /verify HTTP/1.1
Content-Type: application/json
Accept: application/hal+json
Authorization: Bearer eyJ0eXAiOiJKV
Host: localhost:8080
Content-Length: 37

{"googleAccessToken":"ya29.GmMfBEt8"}
$ curl 'http://localhost:8080/verify' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer eyJ0eXAiOiJKV' -d '{"googleAccessToken":"ya29.GmMfBEt8"}'
Response

Example Response

HTTP/1.1 200 OK

Facebook verification

Request

Request Headers

Name Description

Content-Type

The Content-Type of the payload

Accept

The requested Content-Type of the response

Authorization

Should contain the string 'Bearer' plus the token obtained from a Social Network login

Request Fields

Path Type Description

facebookAccessToken

String

A valid access token from Facebook OAuth2 API

Example Request

POST /verify HTTP/1.1
Content-Type: application/json
Accept: application/hal+json
Authorization: Bearer eyJ0eXAiOiJKV
Host: localhost:8080
Content-Length: 40

{"facebookAccessToken":"2.h1MTNeLqcLqw"}
$ curl 'http://localhost:8080/verify' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer eyJ0eXAiOiJKV' -d '{"facebookAccessToken":"2.h1MTNeLqcLqw"}'
Response

Example Response

HTTP/1.1 200 OK

Twitter verification

Request

Request Headers

Name Description

Content-Type

The Content-Type of the payload

Accept

The requested Content-Type of the response

Authorization

Should contain the string 'Bearer' plus the token obtained from a Social Network login

Request Fields

Path Type Description

twitterAccessToken

String

A valid access token from Twitter OAuth API

Example Request

POST /verify HTTP/1.1
Content-Type: application/json
Accept: application/hal+json
Authorization: Bearer eyJ0eXAiOiJKV
Host: localhost:8080
Content-Length: 38

{"twitterAccessToken":"NPcudxy0yU5T3"}
$ curl 'http://localhost:8080/verify' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer eyJ0eXAiOiJKV' -d '{"twitterAccessToken":"NPcudxy0yU5T3"}'
Response

Example Response

HTTP/1.1 200 OK

Accept InVID Invite

Content Owners will usually register in the platform by accepting an invite of an InVID User who wants to reuse one of their UGVs.

In this case, the content owner is also asked to log in using their social network credentials to verify that this user is the owner of the social network account where the video is published.

Accept Invite for YouTube Video

For invitations related to YouTube videos, the UGV is associated to a YouTube channel. However, it is not possible to login directly to a YouTube channel. Uploaders have to login with their Google accounts and authorise the InVID Rights Module to access their YouTube channel’s information through Google API.

The procedure to the the ID Token is the same than for authentication of content owners. However, in this case, it is also necessary to provide an access token for the YouTube channel where the invited video is.

The Google OAuth 2 scope to grant access to the YouTube channel’s information is:

Request

Request Headers

Name Description

Content-Type

The Content-Type of the payload

Accept

The requested Content-Type of the response

Request Fields

Path Type Description

googleIdToken

String

A valid id token from Google API

googleAccessToken

String

A valid access token from Google API

fromInvite

String

A valid InVID Invite ID

Example Request

POST /login HTTP/1.1
Content-Type: application/json
Accept: application/hal+json
Host: localhost:8080
Content-Length: 121

{"googleAccessToken":"ya29.GmMfBEt8","googleIdToken":"eyJ0eXAiOiJKV","fromInvite":"0729c313-fe78-46b9-962b-b5421aa54d3f"}
$ curl 'http://localhost:8080/login' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/hal+json' -d '{"googleAccessToken":"ya29.GmMfBEt8","googleIdToken":"eyJ0eXAiOiJKV","fromInvite":"0729c313-fe78-46b9-962b-b5421aa54d3f"}'
Response

Response Headers

Name Description

Content-Type

The Content-Type of the payload

Response Fields

Path Type Description

id

String

The id of the logged user

username

Null

The username of the logged user

email

String

The email of the logged user

authorities

Array

The roles of the logged user

Example Response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 137

{"id":"8a2d36c4-cd03-4f5d-a3db-e0ea2d707eee","email":"user@gmail.com","username":null,"authorities":[{"authority":"ROLE_CONTENT_OWNER"}]}

Accept Invite for Facebook Video

For invitations related to Facebook videos, the UGV is associated to a Facebook user representing a Facebook Page. However, it is not possible to login directly to a Facebook page. Uploaders have to login with their Facebook accounts and authorise the InVID Rights Module to access their Facebook pages information through Facebook’s Graph API.

The procedure to the the Access Token is the same than for authentication of content owners.

Request

Request Headers

Name Description

Content-Type

The Content-Type of the payload

Accept

The requested Content-Type of the response

Request Fields

Path Type Description

facebookAccessToken

String

A valid access token from Facebook OAuth2 API

fromInvite

String

A valid InVID Invite ID

Example Request

POST /login HTTP/1.1
Content-Type: application/json
Accept: application/hal+json
Host: localhost:8080
Content-Length: 92

{"facebookAccessToken":"2.h1MTNeLqcLqw","fromInvite":"7a44a9c2-f6fb-44fd-87b0-e2bf8e3b3b71"}
$ curl 'http://localhost:8080/login' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/hal+json' -d '{"facebookAccessToken":"2.h1MTNeLqcLqw","fromInvite":"7a44a9c2-f6fb-44fd-87b0-e2bf8e3b3b71"}'
Response

Response Headers

Name Description

Content-Type

The Content-Type of the payload

Response Fields

Path Type Description

id

String

The id of the logged user

username

String

The username of the logged user

email

String

The email of the logged user

authorities

Array

The roles of the logged user

Example Response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 142

{"id":"dc036319-babb-4597-ad19-2c154adb9e3b","email":"user@facebook.com","username":"user","authorities":[{"authority":"ROLE_CONTENT_OWNER"}]}

Accept Reuse Request

In order to accept the CopyrightStatement of a Reuse Request, a ReuseAgreement must be created.

Only Content Owners who have previously verified being the owner of the requested UGV can accept a Reuse Request.

Request

Request Headers

Name Description

Content-Type

The Content-Type of the payload

Accept

The requested Content-Type of the response

Authorization

JWT Authoritzation, HTTPS recommended

Request Fields

Path Type Description

agrees

String

The URI to the Reuse Request to accept

Example Request

POST /reuseAgreements HTTP/1.1
Content-Type: application/json
Accept: application/hal+json
Authorization: Bearer eyJ0eXAiOiJKV
Host: localhost:8080
Content-Length: 65

{"agrees": "/reuseRequests/42030d9c-c8a6-45bf-b8af-100bb128b537"}
$ curl 'http://localhost:8080/reuseAgreements' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer eyJ0eXAiOiJKV' -d '{"agrees": "/reuseRequests/42030d9c-c8a6-45bf-b8af-100bb128b537"}'

Response

Response Headers

Name Description

Content-Type

The Content-Type of the payload

Location

URI of the new Reuse Policy Request registered

Response Fields

Path Type Description

id

String

The id of the Reuse Agreement

dateTime

String

The date-time with a time-zone in the ISO-8601 calendar system, when this reuse agreement was created

_links

Object

Links to related resources detailed in the next table

Response Links

Relation Description

self

The URI of the resource

reuseAgreement

The URI of the resource

agrees

The URI to the Reuse Request which is accepting this agreement

Example Response

HTTP/1.1 201 Created
Location: http://localhost:8080/reuseAgreements/3ac2abd9-cb51-43e8-bc40-11da2766cfc7
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 474

{
  "id" : "3ac2abd9-cb51-43e8-bc40-11da2766cfc7",
  "dateTime" : "2017-11-07T12:38:53.416Z",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/reuseAgreements/3ac2abd9-cb51-43e8-bc40-11da2766cfc7"
    },
    "reuseAgreement" : {
      "href" : "http://localhost:8080/reuseAgreements/3ac2abd9-cb51-43e8-bc40-11da2766cfc7"
    },
    "agrees" : {
      "href" : "http://localhost:8080/reuseAgreements/3ac2abd9-cb51-43e8-bc40-11da2766cfc7/agrees"
    }
  }
}

Reject Reuse Request

In order to reject the CopyrightStatement of a Reuse Request, it is just necessary to change the state of the Reuse Request to 'REJECTED'.

Only Content Owners who have previously verified being the owner of the requested UGV can reject a Reuse Request.

Request

Request Headers

Name Description

Content-Type

The Content-Type of the payload

Accept

The requested Content-Type of the response

Authorization

JWT Authoritzation, HTTPS recommended

Request Fields

Path Type Description

status

String

The new status of the Reuse Request (VIEWED, REJECTED or ACCEPTED)

Example Request

PATCH /reuseRequests/b3b2c896-9ead-4000-bb69-9496e643a9e6 HTTP/1.1
Content-Type: application/json
Accept: application/hal+json
Authorization: Bearer eyJ0eXAiOiJKV
Host: localhost:8080
Content-Length: 22

{"status": "REJECTED"}
$ curl 'http://localhost:8080/reuseRequests/b3b2c896-9ead-4000-bb69-9496e643a9e6' -i -X PATCH -H 'Content-Type: application/json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer eyJ0eXAiOiJKV' -d '{"status": "REJECTED"}'

Response

Response Headers

Name Description

Content-Type

The Content-Type of the payload

Response Fields

Path Type Description

id

String

The id of the Reuse Policy Request

dateTime

String

The date-time with a time-zone in the ISO-8601 calendar system, when this reuse request was created

status

String

The status of the Reuse Policy Request (NEW, VIEWED, REJECTED or ACCEPTED)

statusChanged

Boolean

Indicates if the status has changed from the last time the journalist saw it

lastStatusChange

String

Date-time with a time-zone in the ISO-8601 calendar system, indicating the last time the status of this request changed

_links

Object

Links to related resources detailed in the next table

Response Links

Relation Description

self

The URI of the resource

reuseRequest

The URI of the resource

aboutVideo

The URI to the requested UGV

createdBy

The URI to the InVIDUser owner

inVIDInvite

The URI to the related InVIDInvite

agreedBy

The URI to the agreement indicating that this Reuse Request is accepted

terms

The URI to the reuse terms requesting on this Reuse Request

Example Response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1078

{
  "id" : "b3b2c896-9ead-4000-bb69-9496e643a9e6",
  "dateTime" : "2017-11-07T12:37:57.127Z",
  "status" : "REJECTED",
  "statusChanged" : true,
  "lastStatusChange" : "2017-11-07T12:37:57.177Z",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/reuseRequests/b3b2c896-9ead-4000-bb69-9496e643a9e6"
    },
    "reuseRequest" : {
      "href" : "http://localhost:8080/reuseRequests/b3b2c896-9ead-4000-bb69-9496e643a9e6"
    },
    "createdBy" : {
      "href" : "http://localhost:8080/reuseRequests/b3b2c896-9ead-4000-bb69-9496e643a9e6/createdBy"
    },
    "inVIDInvite" : {
      "href" : "http://localhost:8080/reuseRequests/b3b2c896-9ead-4000-bb69-9496e643a9e6/inVIDInvite"
    },
    "terms" : {
      "href" : "http://localhost:8080/reuseRequests/b3b2c896-9ead-4000-bb69-9496e643a9e6/terms"
    },
    "aboutVideo" : {
      "href" : "http://localhost:8080/reuseRequests/b3b2c896-9ead-4000-bb69-9496e643a9e6/aboutVideo"
    },
    "agreedBy" : {
      "href" : "http://localhost:8080/reuseRequests/b3b2c896-9ead-4000-bb69-9496e643a9e6/agreedBy"
    }
  }
}

Domain Model

jdot