Overview

The InVID Rights Management API deals with the copyright aspects related to 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 to 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

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

However, the IdentityProvider is the module responsible for the management of InVID Users authentication. You can see its documentation at 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, UGVs from Facebook and UGVs from Twitter 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 on 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 metadata is included in the response.

If the video already exists on the platform, the response header includes the location of existing resource with the video metadata. In this case, the metadata is not updated, even if there are changes in the metadata stored by the UGV’s social network. To request that the available metadata is updated, use HTTP PUT instead of POST as detailed next.

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 of 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, 30 Jan 2018 17:50:07 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" : "2018-01-30T17:50:07.698Z",
  "lastUpdateDate" : "2018-01-30T17:50:07.698Z",
  "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"
    },
    "reuseRequests" : {
      "href" : "http://localhost:8080/youTubeVideos/0MlCkZQjI2o/reuseRequests"
    },
    "submitters" : {
      "href" : "http://localhost:8080/youTubeVideos/0MlCkZQjI2o/submitters"
    },
    "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, 30 Jan 2018 17:50:28 GMT
Location: http://localhost:8080/youTubeVideos/Xb0P5t5NQWM
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 2408

{
  "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" : "2018-01-30T17:50:28.585Z",
  "lastUpdateDate" : "2018-01-30T17:50:28.585Z",
  "licensedContent" : false,
  "license" : "youtube",
  "blockedCountries" : null,
  "allowedCountries" : null,
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/youTubeVideos/Xb0P5t5NQWM"
    },
    "youTubeVideo" : {
      "href" : "http://localhost:8080/youTubeVideos/Xb0P5t5NQWM"
    },
    "user" : {
      "href" : "http://localhost:8080/youTubeVideos/Xb0P5t5NQWM/user"
    },
    "submitters" : {
      "href" : "http://localhost:8080/youTubeVideos/Xb0P5t5NQWM/submitters"
    },
    "reuseRequests" : {
      "href" : "http://localhost:8080/youTubeVideos/Xb0P5t5NQWM/reuseRequests"
    },
    "reuseTerms" : {
      "href" : "http://localhost:8080/youTubeVideos/Xb0P5t5NQWM/reuseTerms"
    }
  }
}
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, 30 Jan 2018 17:56:17 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=ba76abca5833eccdeae41c0a59221a87&oe=5AED8639",
  "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" : "2018-01-30T17:56:17.185Z",
  "lastUpdateDate" : "2018-01-30T17:56:17.185Z",
  "_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"
    },
    "submitters" : {
      "href" : "http://localhost:8080/facebookVideos/828216780661083/submitters"
    },
    "user" : {
      "href" : "http://localhost:8080/facebookVideos/828216780661083/user"
    }
  }
}
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, 30 Jan 2018 17:57:35 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=ba76abca5833eccdeae41c0a59221a87&oe=5AED8639",
  "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" : "2018-01-30T17:57:35.925Z",
  "lastUpdateDate" : "2018-01-30T17:57:35.925Z",
  "_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"
    },
    "submitters" : {
      "href" : "http://localhost:8080/facebookVideos/828216780661083/submitters"
    },
    "user" : {
      "href" : "http://localhost:8080/facebookVideos/828216780661083/user"
    }
  }
}
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, 30 Jan 2018 17:48:02 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" : "2018-01-30T17:48:02.227Z",
  "lastUpdateDate" : "2018-01-30T17:48:02.227Z",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/twitterVideos/857179125076963329"
    },
    "twitterVideo" : {
      "href" : "http://localhost:8080/twitterVideos/857179125076963329"
    },
    "user" : {
      "href" : "http://localhost:8080/twitterVideos/857179125076963329/user"
    },
    "submitters" : {
      "href" : "http://localhost:8080/twitterVideos/857179125076963329/submitters"
    },
    "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, 30 Jan 2018 17:53:48 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" : "2018-01-30T17:53:48.336Z",
  "lastUpdateDate" : "2018-01-30T17:53:48.336Z",
  "_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"
    }
  }
}

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 metadata extracted from the YouTube API.

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 metadata extracted from the YouTube API. The metadata is that available when the UGV was registered using a POST request, or the last time a PUT request was performed to update it.

More details about the part of the metadata detailing contact information and the link to the reuse terms associated to the UGV are detailed in the next subsections, after presenting the example request and response.

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, 30 Jan 2018 17:51:29 GMT
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 2406

{
  "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" : "2018-01-30T17:51:29.792Z",
  "lastUpdateDate" : "2018-01-30T17:51:29.792Z",
  "licensedContent" : false,
  "license" : "youtube",
  "blockedCountries" : [ ],
  "allowedCountries" : [ ],
  "_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"
    },
    "user" : {
      "href" : "http://localhost:8080/youTubeVideos/Xb0P5t5NQWM/user"
    },
    "submitters" : {
      "href" : "http://localhost:8080/youTubeVideos/Xb0P5t5NQWM/submitters"
    }
  }
}

Contact Information tags

The "contactInformation" field holds a list of links or emails that can be used to contact the user. This information is extracted from the descriptions that the social network users have defined for their videos and profiles.

We extract any URL in the descriptive text. By default, they are tagged as "other,url" in the response following this format:

  • "contactInformation": { "http://moredetails.info": "other,url", …​

If we can recognise the URL as belonging to one of the supported social networks, we tag them appropriately so this information can be used, for instance, when showing them to the user. The format in this case is "social-network,[Facebook|Twitter|Youtube| Instagram],url", for instance:

  • "contactInformation": { "https://twitter.com/linustech": "social-network,Twitter,url",…​

Additionally, YouTube channels have an "about" page holding links to other social accounts and websites. Each of these links has a "title" that is used to tag them appropriately using the format "link,<title>".

Associated UGV Reuse Terms

The available reuse terms for a UGV are available from one of the links obtained after retrieving the metadata for the UGV as detailed above. Performing and HTTP GET to the URL corresponding to the reuseTerms link, the reuse terms associated to the UGV can be retrieved.

Request

Request Headers

Name Description

Accept

The requested Content-Type of the response

Path Parameters

Table 2. /uGVs/{UGV Identifier}/reuseTerms
Parameter Description

UGV Identifier

The identifier of the UGV

Example Request

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

Response Headers

Name Description

Content-Type

The Content-Type of the payload

Response Fields

Path Type Description

_embedded.defaultReuseTerms.[]

Array

The array of reuse terms associated to the UGV

_embedded.defaultReuseTerms.[].action

String

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

_embedded.defaultReuseTerms.[].when

Null

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

_embedded.defaultReuseTerms.[].duration

Null

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

_embedded.defaultReuseTerms.[].where

Null

Territories where the Reuse Term applies

_embedded.defaultReuseTerms.[].with

Null

Tool or instrument with which the Reuse Term action is performed

_embedded.defaultReuseTerms.[].why

Null

Reason for requesting the Reuse Term

_embedded.defaultReuseTerms.[].how

Null

How the content will be reused

_embedded.defaultReuseTerms.[].preconditions

Null

Preconditions to fulfil before the Reuse Term applies

_embedded.defaultReuseTerms.[].postconditions

Null

Postconditions to fulfil after reusing the content

_embedded.defaultReuseTerms.[].description

String

Textual description of the reuse term

_embedded.defaultReuseTerms.[].status

String

'Permitted' if reuse authorised, 'Prohibited' if forbidden, 'Required' if mandatory

_embedded.defaultReuseTerms.[]._links

Object

Links to resources related to the reuse term

Response Links

Unresolved directive in index.adoc - include::/builds/invid-udl/rights-api/target/generated-snippets/get-ugv-reuse-terms/links.adoc[]

Example Response

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

{
  "_embedded" : {
    "defaultReuseTerms" : [ {
      "action" : "Embed",
      "when" : null,
      "duration" : null,
      "where" : null,
      "with" : null,
      "why" : null,
      "how" : null,
      "preconditions" : null,
      "postconditions" : null,
      "description" : "To insert media in Web pages without requiring authorisation from the content owner. It is based on the rights already granted to YouTube by the owner. Therefore, the embedding should be done following these <a href=\"https://support.google.com/youtube/answer/171780?hl=en\" target=\"_blank\"><b>instructions</b></a>",
      "status" : "Permitted",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/defaultReuseTerms/56b77dc3-866f-4b31-b1c9-e1cad0603ad4"
        },
        "defaultReuseTerm" : {
          "href" : "http://localhost:8080/defaultReuseTerms/56b77dc3-866f-4b31-b1c9-e1cad0603ad4"
        },
        "what" : {
          "href" : "http://localhost:8080/defaultReuseTerms/56b77dc3-866f-4b31-b1c9-e1cad0603ad4/what"
        },
        "who" : {
          "href" : "http://localhost:8080/defaultReuseTerms/56b77dc3-866f-4b31-b1c9-e1cad0603ad4/who"
        }
      }
    }, {
      "action" : "Other Uses",
      "when" : null,
      "duration" : null,
      "where" : null,
      "with" : null,
      "why" : null,
      "how" : null,
      "preconditions" : null,
      "postconditions" : null,
      "description" : "Any other kinds of reuse, like re-broadcasting or re-publishing it.",
      "status" : "Prohibited",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/defaultReuseTerms/50118f92-ad14-4ae4-8ab6-9e81c45f815f"
        },
        "defaultReuseTerm" : {
          "href" : "http://localhost:8080/defaultReuseTerms/50118f92-ad14-4ae4-8ab6-9e81c45f815f"
        },
        "what" : {
          "href" : "http://localhost:8080/defaultReuseTerms/50118f92-ad14-4ae4-8ab6-9e81c45f815f/what"
        },
        "who" : {
          "href" : "http://localhost:8080/defaultReuseTerms/50118f92-ad14-4ae4-8ab6-9e81c45f815f/who"
        }
      }
    } ]
  }
}

Reuse Term

One or more Reuse Terms should be defined before registering a Reuse Request. They determine what particular kinds of reuses are requested.

Only InVID Users can generate Reuse Terms. A POST request is used to create a new Reuse Term and it should define the scope of the term using the request fields described below.

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/317a9cbd-8e09-42d1-b35b-fffea93e1af2"],"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/317a9cbd-8e09-42d1-b35b-fffea93e1af2"],"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/a7cbe676-dc45-4f45-9a04-8efd01631741
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 927

{
  "id" : "a7cbe676-dc45-4f45-9a04-8efd01631741",
  "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/a7cbe676-dc45-4f45-9a04-8efd01631741"
    },
    "reuseTerm" : {
      "href" : "http://localhost:8080/reuseTerms/a7cbe676-dc45-4f45-9a04-8efd01631741"
    },
    "partOf" : {
      "href" : "http://localhost:8080/reuseTerms/a7cbe676-dc45-4f45-9a04-8efd01631741/partOf"
    },
    "who" : {
      "href" : "http://localhost:8080/reuseTerms/a7cbe676-dc45-4f45-9a04-8efd01631741/who"
    },
    "what" : {
      "href" : "http://localhost:8080/reuseTerms/a7cbe676-dc45-4f45-9a04-8efd01631741/what"
    }
  }
}

Reuse Policy

A Reuse Policy is created by any InVID User to define a default pattern for Reuse Terms when generating a new Reuse Request. When the user is a member of an Organisation, the Reuse Policy is also available for the rest of the members of that organisation.

Content Owners can also generate Reuse Policies. In this case, the policy defines the reuse terms the content owner will accept for future Reuse Request. If new Reuse Requests define terms that are included in the Reuse Policies of the owner whose content is requested, the reuse request can be automatically accepted if thus specified in the Reuse Policy. Alternatively, the policy might dictate that the request is directly rejected.

A POST request is used to create Reuse Policies.

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/0d1c536e-df11-44e2-b7ca-660b6f7bfd68"],"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/0d1c536e-df11-44e2-b7ca-660b6f7bfd68"}
$ 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/0d1c536e-df11-44e2-b7ca-660b6f7bfd68"],"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/0d1c536e-df11-44e2-b7ca-660b6f7bfd68"}'

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/796fabda-da08-44c9-b13f-a636ee3f1172
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1079

{
  "id" : "796fabda-da08-44c9-b13f-a636ee3f1172",
  "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/796fabda-da08-44c9-b13f-a636ee3f1172"
    },
    "reusePolicy" : {
      "href" : "http://localhost:8080/reusePolicies/796fabda-da08-44c9-b13f-a636ee3f1172"
    },
    "defaultFor" : {
      "href" : "http://localhost:8080/reusePolicies/796fabda-da08-44c9-b13f-a636ee3f1172/defaultFor"
    },
    "what" : {
      "href" : "http://localhost:8080/reusePolicies/796fabda-da08-44c9-b13f-a636ee3f1172/what"
    },
    "definedBy" : {
      "href" : "http://localhost:8080/reusePolicies/796fabda-da08-44c9-b13f-a636ee3f1172/definedBy"
    },
    "who" : {
      "href" : "http://localhost:8080/reusePolicies/796fabda-da08-44c9-b13f-a636ee3f1172/who"
    }
  }
}

Reuse Request

Before creating a Reuse Request, a Reuse Term must have been created, which should define 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/dc6f2330-0154-4c42-871e-112e4a3ab35a"],"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/dc6f2330-0154-4c42-871e-112e4a3ab35a"],"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 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 Request (NEW, VIEWED, REJECTED or ACCEPTED)

statusChanged

Boolean

Indicates if the status has changed since the last time the journalist who created the request checked 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 of the requested UGV

createdBy

The URI of the InVIDUser performing the request

agreedBy

The URI of the resulting agreement if this Reuse Request has been accepted

terms

The URI to the array of reuse terms requested in this Reuse Request

Example Response

HTTP/1.1 201 Created
Location: http://localhost:8080/reuseRequests/6ba3cefa-ba77-4a49-ab24-4686d4943022
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 943

{
  "id" : "6ba3cefa-ba77-4a49-ab24-4686d4943022",
  "dateTime" : "2018-01-30T17:48:17.947Z",
  "status" : "NEW",
  "statusChanged" : false,
  "lastStatusChange" : "2018-01-30T17:48:17.944Z",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/reuseRequests/6ba3cefa-ba77-4a49-ab24-4686d4943022"
    },
    "reuseRequest" : {
      "href" : "http://localhost:8080/reuseRequests/6ba3cefa-ba77-4a49-ab24-4686d4943022"
    },
    "terms" : {
      "href" : "http://localhost:8080/reuseRequests/6ba3cefa-ba77-4a49-ab24-4686d4943022/terms"
    },
    "agreedBy" : {
      "href" : "http://localhost:8080/reuseRequests/6ba3cefa-ba77-4a49-ab24-4686d4943022/agreedBy"
    },
    "aboutVideo" : {
      "href" : "http://localhost:8080/reuseRequests/6ba3cefa-ba77-4a49-ab24-4686d4943022/aboutVideo"
    },
    "createdBy" : {
      "href" : "http://localhost:8080/reuseRequests/6ba3cefa-ba77-4a49-ab24-4686d4943022/createdBy"
    }
  }
}

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

Unresolved directive in index.adoc - include::/builds/invid-udl/rights-api/target/generated-snippets/retrieve-invid-invite/request-headers.adoc[]

Example Request

Unresolved directive in index.adoc - include::/builds/invid-udl/rights-api/target/generated-snippets/retrieve-invid-invite/http-request.adoc[]

Unresolved directive in index.adoc - include::/builds/invid-udl/rights-api/target/generated-snippets/retrieve-invid-invite/curl-request.adoc[]

Response

Response Headers

Unresolved directive in index.adoc - include::/builds/invid-udl/rights-api/target/generated-snippets/retrieve-invid-invite/response-headers.adoc[]

Response Fields

Unresolved directive in index.adoc - include::/builds/invid-udl/rights-api/target/generated-snippets/retrieve-invid-invite/response-fields.adoc[]

Response Links

Unresolved directive in index.adoc - include::/builds/invid-udl/rights-api/target/generated-snippets/retrieve-invid-invite/links.adoc[]

Example Response

Unresolved directive in index.adoc - include::/builds/invid-udl/rights-api/target/generated-snippets/retrieve-invid-invite/http-response.adoc[]

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 log in directly using their social network credentials or through an invite generated by an InVID User for a particular UGV they uploaded.

Authentication

In order to login as Content Owner with a social account, a POST to /login with the access or id token obtained from the social network authentication service is required. After that, the API will return a JWT, which must be used to do authenticated requests. The JWT can be decoded to obtain the following information:

Name Description

id

Content Owner ID

sub

Content Owner username

email

Content Owner email

scopes

List of authorities of that Content Owner (generally "ROLE_CONTENT_OWNER")

iss

Issuer of the token: "invid"

iat

Time at which the JWT was issued (UNIX time)

exp

Expiration time of the token (UNIX time)

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 "googleAuthCode" 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

googleAuthCode

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

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

Response Headers

Name Description

Content-Type

The Content-Type of the payload

Response Fields

Unresolved directive in index.adoc - include::/builds/invid-udl/rights-api/target/generated-snippets/google-sign-in-authentication-for-content-owners/response-fields.adoc[]

Example Response

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

eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ1c2VyIiwianRpIjoiOTBlYmFkNmMtNGUzZS00NmI0LTg0YmYtMDNlODY5NDMzMDIyIiwiZW1haWwiOiJ1c2VyQGdtYWlsLmNvbSIsInNjb3BlcyI6WyJST0xFX0NPTlRFTlRfT1dORVIiXSwiaXNzIjoiaW52aWQiLCJpYXQiOjE1MTczMzQ1MzYsImV4cCI6MTUyNTExMDUzNn0.l2PAOssd_HztfynPOChYYMF_7raC3ORUpCWcBA1Af1WWnMjJCE7U6QHvvDKckeFV4IiOOoPOyXmpLr41et5XfQ

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 obtained 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 "facebookAuthCode" 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

facebookAuthCode

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: 32

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

Response Headers

Name Description

Content-Type

The Content-Type of the payload

Response Fields

Unresolved directive in index.adoc - include::/builds/invid-udl/rights-api/target/generated-snippets/facebook-sign-in-authentication-for-content-owners/response-fields.adoc[]

Example Response

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

eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ1c2VyIiwianRpIjoiYTM4YmUwMjEtZjcwNy00MTJkLWE4ZGQtOTJkNDk1M2NhODUyIiwiZW1haWwiOiJ1c2VyQGZhY2Vib29rLmNvbSIsInNjb3BlcyI6WyJST0xFX0NPTlRFTlRfT1dORVIiXSwiaXNzIjoiaW52aWQiLCJpYXQiOjE1MTczMzQ3NzYsImV4cCI6MTUyNTExMDc3Nn0.Jl6XzNn-GZuPHyAeowH9i7poRh9LM-iNmVeN07uhXD5xJP882LokfYTZXZMtf49bs1KyLQpTD1RveTfrIQ5roA

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 functionality 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

Unresolved directive in index.adoc - include::/builds/invid-udl/rights-api/target/generated-snippets/twitter-sign-in-authentication-for-content-owners/response-fields.adoc[]

Example Response

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

eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ1c2VyIiwianRpIjoiZjk0ZjQyNTAtYmNmNi00NmUwLWJlN2QtMGY4ZTk2N2ZmM2IyIiwiZW1haWwiOiJ1c2VyQHR3aXR0ZXIuY29tIiwic2NvcGVzIjpbIlJPTEVfQ09OVEVOVF9PV05FUiJdLCJpc3MiOiJpbnZpZCIsImlhdCI6MTUxNzMzNDcyMywiZXhwIjoxNTI1MTEwNzIzfQ.5KSQ1nU2oY4UlB3ks9PE8jUOMAkuT_Pa6HY68-vffNTi-3jqq6efbRjq7wQ7-IGF8RbAeAR6QmD4YDcScY7A6Q

Social account verification

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

  • The user can now log in to the InVID Rights Platform (as Content Owner) using any 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 eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ1c2VyIiwianRpIjoiZGEwMzZjNDgtMzdkNy00OGQ5LTk4YTAtMDk5MDBiOTYzMTdiIiwiZW1haWwiOiJ1c2VyQGdtYWlsLmNvbSIsInNjb3BlcyI6WyJST0xFX0NPTlRFTlRfT1dORVIiXSwiaXNzIjoiaW52aWQiLCJpYXQiOjE1MTczMzQ2NzEsImV4cCI6MTUyNTExMDY3MX0.7oyKuvXpXkzNu2UqBxN3Smc9QE7-c99D-9iO-cUMhTnnbbr4dyNfp7Dgq9UyAjaRlO71f70yTYw18rI4VroCKw
Host: localhost:8080
Content-Length: 33

{"googleAuthCode":"aUt3dYuodWWS"}
$ curl 'http://localhost:8080/verify' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ1c2VyIiwianRpIjoiZGEwMzZjNDgtMzdkNy00OGQ5LTk4YTAtMDk5MDBiOTYzMTdiIiwiZW1haWwiOiJ1c2VyQGdtYWlsLmNvbSIsInNjb3BlcyI6WyJST0xFX0NPTlRFTlRfT1dORVIiXSwiaXNzIjoiaW52aWQiLCJpYXQiOjE1MTczMzQ2NzEsImV4cCI6MTUyNTExMDY3MX0.7oyKuvXpXkzNu2UqBxN3Smc9QE7-c99D-9iO-cUMhTnnbbr4dyNfp7Dgq9UyAjaRlO71f70yTYw18rI4VroCKw' -d '{"googleAuthCode":"aUt3dYuodWWS"}'
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

youtubeAuthCode

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 eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ1c2VyIiwianRpIjoiMTMzZjgxM2QtNjA2Yi00ODllLWIxYjktNGNmMGFmMTAyZDFjIiwiZW1haWwiOiJ1c2VyQGdtYWlsLmNvbSIsInNjb3BlcyI6WyJST0xFX0NPTlRFTlRfT1dORVIiXSwiaXNzIjoiaW52aWQiLCJpYXQiOjE1MTczMzQ5MjYsImV4cCI6MTUyNTExMDkyNn0.Ro2EoLiK-BbNqXLTXipjNkBO3fhCZEcDtOJCGjMx6GyqqZ2wRo-V0BWYUHi7pZEBECRY-PN6FV55XpSfUsspsw
Host: localhost:8080
Content-Length: 34

{"youtubeAuthCode":"aUt3dYuodWWS"}
$ curl 'http://localhost:8080/verify' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ1c2VyIiwianRpIjoiMTMzZjgxM2QtNjA2Yi00ODllLWIxYjktNGNmMGFmMTAyZDFjIiwiZW1haWwiOiJ1c2VyQGdtYWlsLmNvbSIsInNjb3BlcyI6WyJST0xFX0NPTlRFTlRfT1dORVIiXSwiaXNzIjoiaW52aWQiLCJpYXQiOjE1MTczMzQ5MjYsImV4cCI6MTUyNTExMDkyNn0.Ro2EoLiK-BbNqXLTXipjNkBO3fhCZEcDtOJCGjMx6GyqqZ2wRo-V0BWYUHi7pZEBECRY-PN6FV55XpSfUsspsw' -d '{"youtubeAuthCode":"aUt3dYuodWWS"}'
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

facebookAuthCode

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 eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ1c2VyIiwianRpIjoiZTNlNGI1ZWQtZmIzZC00OTk0LTljM2YtNjc5ZWY0NDg0NGM1IiwiZW1haWwiOiJ1c2VyQGdtYWlsLmNvbSIsInNjb3BlcyI6WyJST0xFX0NPTlRFTlRfT1dORVIiXSwiaXNzIjoiaW52aWQiLCJpYXQiOjE1MTczMzQ3NTEsImV4cCI6MTUyNTExMDc1MX0.RCQIBTVl5_X4PVR45DTfxomQEb-FMyARJQC5EfeeoDFwyn4IyS6ElEDMOOifsIbCPyZ-aaqbYg0xUq2R0pNFcw
Host: localhost:8080
Content-Length: 32

{"facebookAuthCode":"aUt3d45fB"}
$ curl 'http://localhost:8080/verify' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ1c2VyIiwianRpIjoiZTNlNGI1ZWQtZmIzZC00OTk0LTljM2YtNjc5ZWY0NDg0NGM1IiwiZW1haWwiOiJ1c2VyQGdtYWlsLmNvbSIsInNjb3BlcyI6WyJST0xFX0NPTlRFTlRfT1dORVIiXSwiaXNzIjoiaW52aWQiLCJpYXQiOjE1MTczMzQ3NTEsImV4cCI6MTUyNTExMDc1MX0.RCQIBTVl5_X4PVR45DTfxomQEb-FMyARJQC5EfeeoDFwyn4IyS6ElEDMOOifsIbCPyZ-aaqbYg0xUq2R0pNFcw' -d '{"facebookAuthCode":"aUt3d45fB"}'
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 eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ1c2VyIiwianRpIjoiZWY4NDQyZTEtNjJjYS00OTkzLTg2ZGEtNTlmNzcwNGNjNWMzIiwiZW1haWwiOiJ1c2VyQGdtYWlsLmNvbSIsInNjb3BlcyI6WyJST0xFX0NPTlRFTlRfT1dORVIiXSwiaXNzIjoiaW52aWQiLCJpYXQiOjE1MTczMzUwMjAsImV4cCI6MTUyNTExMTAyMH0.xBPpkLbXeCW5t07b-IIpw19FXvqzS1vibKT93MUdzdtFXHRgV6j8MeQVAPVmftrzBMO9HUyct_IFeqgAYt4gbw
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 eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ1c2VyIiwianRpIjoiZWY4NDQyZTEtNjJjYS00OTkzLTg2ZGEtNTlmNzcwNGNjNWMzIiwiZW1haWwiOiJ1c2VyQGdtYWlsLmNvbSIsInNjb3BlcyI6WyJST0xFX0NPTlRFTlRfT1dORVIiXSwiaXNzIjoiaW52aWQiLCJpYXQiOjE1MTczMzUwMjAsImV4cCI6MTUyNTExMTAyMH0.xBPpkLbXeCW5t07b-IIpw19FXvqzS1vibKT93MUdzdtFXHRgV6j8MeQVAPVmftrzBMO9HUyct_IFeqgAYt4gbw' -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 with a YouTube channel. However, it is not possible to login directly to a YouTube channel. Uploaders have to log in to their Google accounts and authorise the InVID Rights Module to access their YouTube channel’s information through Google API.

The procedure for 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

Unresolved directive in index.adoc - include::/builds/invid-udl/rights-api/target/generated-snippets/google-sign-in-authentication-from-invite-for-content-owners/request-headers.adoc[]

Request Fields

Unresolved directive in index.adoc - include::/builds/invid-udl/rights-api/target/generated-snippets/google-sign-in-authentication-from-invite-for-content-owners/request-fields.adoc[]

Example Request

Unresolved directive in index.adoc - include::/builds/invid-udl/rights-api/target/generated-snippets/google-sign-in-authentication-from-invite-for-content-owners/http-request.adoc[]

Unresolved directive in index.adoc - include::/builds/invid-udl/rights-api/target/generated-snippets/google-sign-in-authentication-from-invite-for-content-owners/curl-request.adoc[]

Response

Response Headers

Unresolved directive in index.adoc - include::/builds/invid-udl/rights-api/target/generated-snippets/google-sign-in-authentication-from-invite-for-content-owners/response-headers.adoc[]

Example Response

Unresolved directive in index.adoc - include::/builds/invid-udl/rights-api/target/generated-snippets/google-sign-in-authentication-from-invite-for-content-owners/http-response.adoc[]

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 log in to their Facebook accounts and authorise the InVID Rights Module to access their Facebook pages information through Facebook’s Graph API.

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

Request

Request Headers

Unresolved directive in index.adoc - include::/builds/invid-udl/rights-api/target/generated-snippets/facebook-sign-in-authentication-from-invite-for-content-owners/request-headers.adoc[]

Request Fields

Unresolved directive in index.adoc - include::/builds/invid-udl/rights-api/target/generated-snippets/facebook-sign-in-authentication-from-invite-for-content-owners/request-fields.adoc[]

Example Request

Unresolved directive in index.adoc - include::/builds/invid-udl/rights-api/target/generated-snippets/facebook-sign-in-authentication-from-invite-for-content-owners/http-request.adoc[]

Unresolved directive in index.adoc - include::/builds/invid-udl/rights-api/target/generated-snippets/facebook-sign-in-authentication-from-invite-for-content-owners/curl-request.adoc[]

Response

Response Headers

Unresolved directive in index.adoc - include::/builds/invid-udl/rights-api/target/generated-snippets/facebook-sign-in-authentication-from-invite-for-content-owners/response-headers.adoc[]

Example Response

Unresolved directive in index.adoc - include::/builds/invid-udl/rights-api/target/generated-snippets/facebook-sign-in-authentication-from-invite-for-content-owners/http-response.adoc[]

Accept Invite for Twitter Video

For invitations related to Twitter videos, the UGV is associated to the corresponding Twitter user. Consequently, the uploader has to log in using the corresponding Twitter credentials and authorise the InVID Rights Module to access their Twitter profile and check the the UGV is present.

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

Example Response

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

eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ1c2VyIiwianRpIjoiYWJjMTE1MjctNWM1YS00MTg3LWI5OWEtMjVhMDk5NDMwM2JmIiwiZW1haWwiOiJ1c2VyQHR3aXR0ZXIuY29tIiwic2NvcGVzIjpbIlJPTEVfQ09OVEVOVF9PV05FUiJdLCJpc3MiOiJpbnZpZCIsImlhdCI6MTUxNzMzNDgwMiwiZXhwIjoxNTI1MTEwODAyfQ.WoCE6ma0xb_tJR0SPfYU8rjdp_OpFuPTCxP8j55BAVxUNFmaEd_v_bvXgnfsA2vBC5rFLEr03B9b2uhAWXoIeg

List Reuse Requests

Content owners can review the Reuse Request they receive by following the links they receive through invites (if not yet registered) or through e-mails (if already registered). Moreover, once registered and authenticated, they can list all the reuse requests directed to them performing an HTTP GET to "/reuseRequests", as detailed next.

Request

Request Headers

Name Description

Accept

The requested Content-Type of the response

Authorization

JWT Authoritzation, HTTPS recommended

Example Request

GET /reuseRequests HTTP/1.1
Accept: application/hal+json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ1c2VyIiwianRpIjoiOWVhMWJhMDUtYjljNS00MzkyLTk5MzAtYzY3NDdhMmM5YTI3IiwiZW1haWwiOiJ1c2VyQGdtYWlsLmNvbSIsInNjb3BlcyI6WyJST0xFX0NPTlRFTlRfT1dORVIiXSwiaXNzIjoiaW52aWQiLCJpYXQiOjE1MTczMzQ2NTIsImV4cCI6MTUyNTExMDY1Mn0.XlyrwB-wRFrRQM-ZChcd_WyQYqSNbCuFUm1YbNTAlt0HR0aZb9_lauQUZXwC7ztT5mu1B7GvQ6elp0w-5XCcRw
Host: localhost:8080
$ curl 'http://localhost:8080/reuseRequests' -i -H 'Accept: application/hal+json' -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ1c2VyIiwianRpIjoiOWVhMWJhMDUtYjljNS00MzkyLTk5MzAtYzY3NDdhMmM5YTI3IiwiZW1haWwiOiJ1c2VyQGdtYWlsLmNvbSIsInNjb3BlcyI6WyJST0xFX0NPTlRFTlRfT1dORVIiXSwiaXNzIjoiaW52aWQiLCJpYXQiOjE1MTczMzQ2NTIsImV4cCI6MTUyNTExMDY1Mn0.XlyrwB-wRFrRQM-ZChcd_WyQYqSNbCuFUm1YbNTAlt0HR0aZb9_lauQUZXwC7ztT5mu1B7GvQ6elp0w-5XCcRw'

Response

Response Headers

Name Description

Content-Type

The Content-Type of the payload

Response Fields

Path Type Description

page

Object

Pagination information

_links

Object

Links to related resources detailed in the next table

_embedded.reuseRequests.[]

Array

The array of reuse requests associated to the current user

_embedded.reuseRequests.[].id

String

The id of the Reuse Request

_embedded.reuseRequests.[].dateTime

String

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

_embedded.reuseRequests.[].status

String

The status of the Reuse Request, should be now REJECTED

_embedded.reuseRequests.[].statusChanged

Boolean

Indicates if the status has changed since the last time the journalist who created the request checked it

_embedded.reuseRequests.[].lastStatusChange

String

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

_embedded.reuseRequests.[]._links

Object

Links to resources related to the reuse request

Response Links

Relation Description

self

The URI of the current list of reuse requests

profile

Link to the profile of this part of the API

search

Link to the API method to search reuse requests

Example Response

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

{
  "_embedded" : {
    "reuseRequests" : [ {
      "id" : "30525f8d-37df-4535-b613-96ceeaf98a2d",
      "dateTime" : "2018-01-30T17:50:52.198Z",
      "status" : "NEW",
      "statusChanged" : false,
      "lastStatusChange" : "2018-01-30T17:50:52.197Z",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/reuseRequests/30525f8d-37df-4535-b613-96ceeaf98a2d"
        },
        "reuseRequest" : {
          "href" : "http://localhost:8080/reuseRequests/30525f8d-37df-4535-b613-96ceeaf98a2d"
        },
        "terms" : {
          "href" : "http://localhost:8080/reuseRequests/30525f8d-37df-4535-b613-96ceeaf98a2d/terms"
        },
        "agreedBy" : {
          "href" : "http://localhost:8080/reuseRequests/30525f8d-37df-4535-b613-96ceeaf98a2d/agreedBy"
        },
        "createdBy" : {
          "href" : "http://localhost:8080/reuseRequests/30525f8d-37df-4535-b613-96ceeaf98a2d/createdBy"
        },
        "aboutVideo" : {
          "href" : "http://localhost:8080/reuseRequests/30525f8d-37df-4535-b613-96ceeaf98a2d/aboutVideo"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/reuseRequests"
    },
    "profile" : {
      "href" : "http://localhost:8080/profile/reuseRequests"
    },
    "search" : {
      "href" : "http://localhost:8080/reuseRequests/search"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 0
  }
}

Accept Reuse Request

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 eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ1c2VyIiwianRpIjoiZmRiYTAxOGMtZDg4MC00ZTdmLThjMTctZmJlYWIwODg2OGRkIiwiZW1haWwiOiJ1c2VyQGdtYWlsLmNvbSIsInNjb3BlcyI6WyJST0xFX0NPTlRFTlRfT1dORVIiXSwiaXNzIjoiaW52aWQiLCJpYXQiOjE1MTczMzUxMDksImV4cCI6MTUyNTExMTEwOX0.DmELqI34raR6P5uE7hWmB9eKjpNp0trViVELCeFXGrKwPRbLr_vGf5b0WdCh9gj1YcG8TrKYwum9s98RfjhNJg
Host: localhost:8080
Content-Length: 65

{"agrees": "/reuseRequests/b66ca5da-3312-45ef-8490-429a2daace9e"}
$ curl 'http://localhost:8080/reuseAgreements' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ1c2VyIiwianRpIjoiZmRiYTAxOGMtZDg4MC00ZTdmLThjMTctZmJlYWIwODg2OGRkIiwiZW1haWwiOiJ1c2VyQGdtYWlsLmNvbSIsInNjb3BlcyI6WyJST0xFX0NPTlRFTlRfT1dORVIiXSwiaXNzIjoiaW52aWQiLCJpYXQiOjE1MTczMzUxMDksImV4cCI6MTUyNTExMTEwOX0.DmELqI34raR6P5uE7hWmB9eKjpNp0trViVELCeFXGrKwPRbLr_vGf5b0WdCh9gj1YcG8TrKYwum9s98RfjhNJg' -d '{"agrees": "/reuseRequests/b66ca5da-3312-45ef-8490-429a2daace9e"}'

Response

Response Headers

Name Description

Content-Type

The Content-Type of the payload

Location

URI of the new Reuse Agreement

Response Fields

Path Type Description

id

String

The id of the new 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 accepted by this agreement

Example Response

HTTP/1.1 201 Created
Location: http://localhost:8080/reuseAgreements/090a4fc6-aac6-44be-aad9-89028d42a37a
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 474

{
  "id" : "090a4fc6-aac6-44be-aad9-89028d42a37a",
  "dateTime" : "2018-01-30T17:58:29.384Z",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/reuseAgreements/090a4fc6-aac6-44be-aad9-89028d42a37a"
    },
    "reuseAgreement" : {
      "href" : "http://localhost:8080/reuseAgreements/090a4fc6-aac6-44be-aad9-89028d42a37a"
    },
    "agrees" : {
      "href" : "http://localhost:8080/reuseAgreements/090a4fc6-aac6-44be-aad9-89028d42a37a/agrees"
    }
  }
}

Reject Reuse Request

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, in this case REJECTED

Example Request

PATCH /reuseRequests/072f211d-60e0-4fc1-90fa-bce260a9c012 HTTP/1.1
Content-Type: application/json
Accept: application/hal+json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ1c2VyIiwianRpIjoiZjE1ODYyMDAtOGE3Yy00MjRhLWIyMWEtMWM3Y2JiYTA5ZWEyIiwiZW1haWwiOiJ1c2VyQGdtYWlsLmNvbSIsInNjb3BlcyI6WyJST0xFX0NPTlRFTlRfT1dORVIiXSwiaXNzIjoiaW52aWQiLCJpYXQiOjE1MTczMzQ1NjYsImV4cCI6MTUyNTExMDU2Nn0.mDlVGieR-33ZdGGPU25h57IxMbp1bMEOv7j6Y9fu4dsXU9qoMPSynHGhnk5c8WQ-odnCOWn5I6JEgxjPqhA3sw
Host: localhost:8080
Content-Length: 22

{"status": "REJECTED"}
$ curl 'http://localhost:8080/reuseRequests/072f211d-60e0-4fc1-90fa-bce260a9c012' -i -X PATCH -H 'Content-Type: application/json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ1c2VyIiwianRpIjoiZjE1ODYyMDAtOGE3Yy00MjRhLWIyMWEtMWM3Y2JiYTA5ZWEyIiwiZW1haWwiOiJ1c2VyQGdtYWlsLmNvbSIsInNjb3BlcyI6WyJST0xFX0NPTlRFTlRfT1dORVIiXSwiaXNzIjoiaW52aWQiLCJpYXQiOjE1MTczMzQ1NjYsImV4cCI6MTUyNTExMDU2Nn0.mDlVGieR-33ZdGGPU25h57IxMbp1bMEOv7j6Y9fu4dsXU9qoMPSynHGhnk5c8WQ-odnCOWn5I6JEgxjPqhA3sw' -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 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 Request, should be now REJECTED

statusChanged

Boolean

Indicates if the status has changed since the last time the journalist who created the request checked 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 of the requested UGV

createdBy

The URI of the InVIDUser performing the request

agreedBy

This link will not point to any existing resource because the request has not been accepted, thus HTTP 404 NOT FOUND

terms

The URI to the array of reuse terms requested in this Reuse Request

Example Response

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

{
  "id" : "072f211d-60e0-4fc1-90fa-bce260a9c012",
  "dateTime" : "2018-01-30T17:49:26.627Z",
  "status" : "REJECTED",
  "statusChanged" : true,
  "lastStatusChange" : "2018-01-30T17:49:26.642Z",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/reuseRequests/072f211d-60e0-4fc1-90fa-bce260a9c012"
    },
    "reuseRequest" : {
      "href" : "http://localhost:8080/reuseRequests/072f211d-60e0-4fc1-90fa-bce260a9c012"
    },
    "aboutVideo" : {
      "href" : "http://localhost:8080/reuseRequests/072f211d-60e0-4fc1-90fa-bce260a9c012/aboutVideo"
    },
    "createdBy" : {
      "href" : "http://localhost:8080/reuseRequests/072f211d-60e0-4fc1-90fa-bce260a9c012/createdBy"
    },
    "agreedBy" : {
      "href" : "http://localhost:8080/reuseRequests/072f211d-60e0-4fc1-90fa-bce260a9c012/agreedBy"
    },
    "terms" : {
      "href" : "http://localhost:8080/reuseRequests/072f211d-60e0-4fc1-90fa-bce260a9c012/terms"
    }
  }
}

Domain Model

jdot