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

Additionally, once the InVID User has obtained the JWT from the IdentityProvider, they can use it to retrieve their profile information through the following call:

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

Example Request

GET /identity HTTP/1.1
Content-Type: application/json
Accept: application/hal+json
Authorization: Bearer INVID_VALID_TOKEN
Host: localhost:8080
$ curl 'http://localhost:8080/identity' -i -H 'Content-Type: application/json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer INVID_VALID_TOKEN'

Response

Response Fields

Path Type Description

id

String

The id of the logged user

gravatarCode

Null

The code from gravatar

username

String

Username of the logged user

email

String

Email of the logged user

description

Null

Brief description of the logged user

authorities

Array

Active roles of the logged user

notifications

Boolean

Indicates whether this user has enabled email notifications or not

_links

Object

Links to related resources detailed in the next table

Response Links

Relation Description

self

The URI of the resource

inVIDUser

The URI of the resource

reuseRequests

The URIs of the ReuseRequests submitted by this user

agentOf

The URIs of the ReuseTerms for this user

organization

The URI of the organization of this user

templates

The URIs of the ReuseTemplates defined by this user

Example Response

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

{
  "id" : "31d372e1-1837-4531-9b4f-013c6a14ebf7",
  "gravatarCode" : null,
  "notifications" : true,
  "username" : "Clark Kent",
  "email" : "journalist@invid-project.eu",
  "description" : null,
  "authorities" : [ {
    "authority" : "ROLE_INVID"
  } ],
  "password" : null,
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/inVIDUsers/31d372e1-1837-4531-9b4f-013c6a14ebf7"
    },
    "inVIDUser" : {
      "href" : "http://localhost:8080/inVIDUsers/31d372e1-1837-4531-9b4f-013c6a14ebf7"
    },
    "hasSubmitted" : {
      "href" : "http://localhost:8080/inVIDUsers/31d372e1-1837-4531-9b4f-013c6a14ebf7/hasSubmitted"
    },
    "templates" : {
      "href" : "http://localhost:8080/inVIDUsers/31d372e1-1837-4531-9b4f-013c6a14ebf7/templates"
    },
    "agentOf" : {
      "href" : "http://localhost:8080/inVIDUsers/31d372e1-1837-4531-9b4f-013c6a14ebf7/agentOf"
    },
    "organization" : {
      "href" : "http://localhost:8080/inVIDUsers/31d372e1-1837-4531-9b4f-013c6a14ebf7/organization"
    },
    "reuseRequests" : {
      "href" : "http://localhost:8080/inVIDUsers/31d372e1-1837-4531-9b4f-013c6a14ebf7/reuseRequests"
    }
  }
}

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: Fri, 07 Sep 2018 08:43:36 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-09-07T08:43:36.309Z",
  "lastUpdateDate" : "2018-09-07T08:43:36.309Z",
  "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"
    },
    "reuseTerms" : {
      "href" : "http://localhost:8080/youTubeVideos/0MlCkZQjI2o/reuseTerms"
    },
    "reuseRequests" : {
      "href" : "http://localhost:8080/youTubeVideos/0MlCkZQjI2o/reuseRequests"
    }
  }
}
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: Fri, 07 Sep 2018 08:43:40 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-09-07T08:43:40.082Z",
  "lastUpdateDate" : "2018-09-07T08:43:40.082Z",
  "licensedContent" : false,
  "license" : "youtube",
  "blockedCountries" : null,
  "allowedCountries" : null,
  "_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"
    },
    "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: Fri, 07 Sep 2018 08:44:24 GMT
Location: http://localhost:8080/facebookVideos/828216780661083
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1450

{
  "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?_nc_cat=0&oh=961a1a6936371e67a8a2a2bb0781b65b&oe=5C29EE39",
  "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-09-07T08:44:24.246Z",
  "lastUpdateDate" : "2018-09-07T08:44:24.246Z",
  "_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"
    }
  }
}
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: Fri, 07 Sep 2018 08:44:30 GMT
Location: http://localhost:8080/facebookVideos/828216780661083
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1450

{
  "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?_nc_cat=0&oh=961a1a6936371e67a8a2a2bb0781b65b&oe=5C29EE39",
  "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-09-07T08:44:30.336Z",
  "lastUpdateDate" : "2018-09-07T08:44:30.336Z",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/facebookVideos/828216780661083"
    },
    "facebookVideo" : {
      "href" : "http://localhost:8080/facebookVideos/828216780661083"
    },
    "reuseTerms" : {
      "href" : "http://localhost:8080/facebookVideos/828216780661083/reuseTerms"
    },
    "submitters" : {
      "href" : "http://localhost:8080/facebookVideos/828216780661083/submitters"
    },
    "reuseRequests" : {
      "href" : "http://localhost:8080/facebookVideos/828216780661083/reuseRequests"
    },
    "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: Fri, 07 Sep 2018 08:43:12 GMT
Location: http://localhost:8080/twitterVideos/857179125076963329
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1255

{
  "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" : "https://pbs.twimg.com/ext_tw_video_thumb/857179018365370369/pu/img/TSzFWWUvUnaICKEm.jpg",
  "description" : null,
  "contactInformation" : { },
  "registeredDate" : "2018-09-07T08:43:12.731Z",
  "lastUpdateDate" : "2018-09-07T08:43:12.731Z",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/twitterVideos/857179125076963329"
    },
    "twitterVideo" : {
      "href" : "http://localhost:8080/twitterVideos/857179125076963329"
    },
    "reuseTerms" : {
      "href" : "http://localhost:8080/twitterVideos/857179125076963329/reuseTerms"
    },
    "user" : {
      "href" : "http://localhost:8080/twitterVideos/857179125076963329/user"
    },
    "reuseRequests" : {
      "href" : "http://localhost:8080/twitterVideos/857179125076963329/reuseRequests"
    },
    "submitters" : {
      "href" : "http://localhost:8080/twitterVideos/857179125076963329/submitters"
    }
  }
}
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: Fri, 07 Sep 2018 08:44:11 GMT
Location: http://localhost:8080/twitterVideos/857179125076963329
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1255

{
  "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" : "https://pbs.twimg.com/ext_tw_video_thumb/857179018365370369/pu/img/TSzFWWUvUnaICKEm.jpg",
  "description" : null,
  "contactInformation" : { },
  "registeredDate" : "2018-09-07T08:44:11.156Z",
  "lastUpdateDate" : "2018-09-07T08:44:11.156Z",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/twitterVideos/857179125076963329"
    },
    "twitterVideo" : {
      "href" : "http://localhost:8080/twitterVideos/857179125076963329"
    },
    "user" : {
      "href" : "http://localhost:8080/twitterVideos/857179125076963329/user"
    },
    "reuseRequests" : {
      "href" : "http://localhost:8080/twitterVideos/857179125076963329/reuseRequests"
    },
    "submitters" : {
      "href" : "http://localhost:8080/twitterVideos/857179125076963329/submitters"
    },
    "reuseTerms" : {
      "href" : "http://localhost:8080/twitterVideos/857179125076963329/reuseTerms"
    }
  }
}

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: Fri, 07 Sep 2018 08:43:48 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-09-07T08:43:48.987Z",
  "lastUpdateDate" : "2018-09-07T08:43:48.987Z",
  "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"
    },
    "submitters" : {
      "href" : "http://localhost:8080/youTubeVideos/Xb0P5t5NQWM/submitters"
    },
    "reuseRequests" : {
      "href" : "http://localhost:8080/youTubeVideos/Xb0P5t5NQWM/reuseRequests"
    },
    "user" : {
      "href" : "http://localhost:8080/youTubeVideos/Xb0P5t5NQWM/user"
    }
  }
}

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.[].endDate

Null

Date-time with a time-zone in the ISO-8601 calendar system, until which the ReuseTerm 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.[].conditions

Null

Attribution message for this specific ReuseTerm

_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: 2223

{
  "_embedded" : {
    "defaultReuseTerms" : [ {
      "action" : "Embed",
      "when" : null,
      "endDate" : null,
      "where" : null,
      "with" : null,
      "why" : null,
      "how" : null,
      "conditions" : null,
      "postconditions" : null,
      "scope" : null,
      "what" : 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/c877cfd7-f5c2-4e59-b5f4-09f32b255696"
        },
        "defaultReuseTerm" : {
          "href" : "http://localhost:8080/defaultReuseTerms/c877cfd7-f5c2-4e59-b5f4-09f32b255696"
        },
        "who" : {
          "href" : "http://localhost:8080/defaultReuseTerms/c877cfd7-f5c2-4e59-b5f4-09f32b255696/who"
        },
        "requestUGV" : {
          "href" : "http://localhost:8080/defaultReuseTerms/c877cfd7-f5c2-4e59-b5f4-09f32b255696/requestUGV"
        }
      }
    }, {
      "action" : "Other Uses",
      "when" : null,
      "endDate" : null,
      "where" : null,
      "with" : null,
      "why" : null,
      "how" : null,
      "conditions" : null,
      "postconditions" : null,
      "scope" : null,
      "what" : null,
      "description" : "Any other kinds of reuse, like re-broadcasting or re-publishing it.",
      "status" : "Prohibited",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/defaultReuseTerms/efecd6ca-0e38-4e62-8a0e-7fd531647758"
        },
        "defaultReuseTerm" : {
          "href" : "http://localhost:8080/defaultReuseTerms/efecd6ca-0e38-4e62-8a0e-7fd531647758"
        },
        "who" : {
          "href" : "http://localhost:8080/defaultReuseTerms/efecd6ca-0e38-4e62-8a0e-7fd531647758/who"
        },
        "requestUGV" : {
          "href" : "http://localhost:8080/defaultReuseTerms/efecd6ca-0e38-4e62-8a0e-7fd531647758/requestUGV"
        }
      }
    } ]
  }
}

Reuse Request Negotiation

When any journalist wants rights for a given UGV, he or she will have to open a new negotiation process in which both parts will discuss which are the appropriate rights. This process is implemented in the API through three classes:

  • ReuseTerm: Contains the reuse conditions over which the negotiation is being done.

  • ReuseNegotiationStep: Represents a step of the negotiation between the journalist and the owner of the video.

  • ReuseRequest: Represents the request a journalist does asking for rights about an UGV.

Next, we describe the process of negotiating the rights of a UGV.

  1. The journalist creates some ReuseTerm specifying the conditions of reuse they need.

  2. The journalist creates a ReuseNegotiationStep with a message for the owner of the UGV and the ReuseTerms associated.

  3. The journalist creates a ReuseRequest associated to the previous ReuseNegotiationStep.

  4. Now the owner of the UGV have to answer to the ReuseRequest and they have two options.

    • Accept the ReuseTerms purposed by the journalist creating a ReuseAgreement. In this case, there would not be any negotiation and the process would end here.

    • Disagree with the purposed ReuseTerms and modify them showing the version you would accept. In this case, the process continues with step 5.

  5. The owner creates some ReuseTerm, based on the ones created by the journalist, specifying the conditions they would accept.

  6. The owner creates a ReuseNegotiationStep with a message to answer to the journalist and the ReuseTerms associated. This ReuseNegotiationStep is also associated with the ReuseRequest.

  7. Now is the journalist who has to answer whether agreeing with the purposed ReuseTerms or creating a new ReuseNegotiationStep.

Reuse Term

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

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)

requestUGV

Array

URI(s) of the content to which the Reuse Term is based

scope

String

The scope to which the Reuse Term applies. This field have three possible values: UGV, ExternalUser and ContentOwner

when

String

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

endDate

String

Date-time with a time-zone in the ISO-8601 calendar system, until which the ReuseTerm 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

conditions

String

Attribution message for this specific ReuseTerm

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

{ "action": "Make Available","who": ["/organizations/35cf68ab-38ca-4f7b-9350-448431a645b7"],"requestUGV": ["/uGVs/Xb0P5t5NQWM"],"scope": "UGV","when": "2018-09-07T08:43:24.131Z[Etc/UTC]","endDate": "2018-12-07T08:43:24.132Z[Etc/UTC]","where": "Spain","with": "TV","why": "To broadcast it on TV news","how": "Broadcast on TV","conditions": "Video from InVID retrieved from their YouTube channel","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": "Make Available","who": ["/organizations/35cf68ab-38ca-4f7b-9350-448431a645b7"],"requestUGV": ["/uGVs/Xb0P5t5NQWM"],"scope": "UGV","when": "2018-09-07T08:43:24.131Z[Etc/UTC]","endDate": "2018-12-07T08:43:24.132Z[Etc/UTC]","where": "Spain","with": "TV","why": "To broadcast it on TV news","how": "Broadcast on TV","conditions": "Video from InVID retrieved from their YouTube channel","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'

scope

String

The scope to which the Reuse Term applies. This field have three possible values: UGV, ExternalUser and ContentOwner

when

String

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

endDate

String

Date-time with a time-zone in the ISO-8601 calendar system, until which the ReuseTerm 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

conditions

String

Attribution message for this specific ReuseTerm

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)

requestUGV

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

Example Response

HTTP/1.1 201 Created
Location: http://localhost:8080/reuseTerms/b0970188-097f-429b-be28-e4ebf509a2bc
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 902

{
  "id" : "b0970188-097f-429b-be28-e4ebf509a2bc",
  "action" : "Make Available",
  "when" : "2018-09-07T08:43:24.131Z",
  "endDate" : "2018-12-07T08:43:24.132Z",
  "where" : "Spain",
  "with" : "TV",
  "why" : "To broadcast it on TV news",
  "how" : "Broadcast on TV",
  "conditions" : "Video from InVID retrieved from their YouTube channel",
  "postconditions" : "No Post Condition",
  "scope" : "UGV",
  "what" : null,
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/reuseTerms/b0970188-097f-429b-be28-e4ebf509a2bc"
    },
    "reuseTerm" : {
      "href" : "http://localhost:8080/reuseTerms/b0970188-097f-429b-be28-e4ebf509a2bc"
    },
    "requestUGV" : {
      "href" : "http://localhost:8080/reuseTerms/b0970188-097f-429b-be28-e4ebf509a2bc/requestUGV"
    },
    "who" : {
      "href" : "http://localhost:8080/reuseTerms/b0970188-097f-429b-be28-e4ebf509a2bc/who"
    }
  }
}

Reuse Negotiation Step

The Reuse Negotiation Step represents a step in the negotiation for the rights of a UGV. It can be created by a journalist or by the owner of a UGV in response to the initial request of the journalist. A Reuse Negotiation Step can be modified (by creating a new one that will substitute the last) only if it has not been seen by the other part of the negotiation.

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

message

String

A message for comunicating with the other interactor of the Reuse Request.

terms

Array

A list of URIs of the ReuseTerms associated with this negotiation step.

request

class java.lang.String

The URI of the Reuse Request this negotiation step belongs to. Only if it’s not the first step.

Example Request

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

{"message": "I'd like to reuse your video","terms": ["/reuseTerms/88587614-f5be-4aa8-bcbd-c69b55327bd2"]}
$ curl 'http://localhost:8080/reuseNegotiationSteps' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer INVID_VALID_TOKEN' -d '{"message": "I'd like to reuse your video","terms": ["/reuseTerms/88587614-f5be-4aa8-bcbd-c69b55327bd2"]}'
Response

Response Headers

Name Description

Content-Type

The Content-Type of the payload

Location

URI of the new Reuse Negotiatio Step registered

Response Fields

Path Type Description

id

String

The id of the Reuse Negotiation Step

message

String

A message for comunicating with the other interactor of the Reuse Request.

dateTime

String

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

_links

Object

Links to related resources detailed in the next table

Response Links

Relation Description

self

The URI of the resource.

reuseNegotiationStep

The URI of the resource.

creator

The URI of the creator of this step.

request

The URI of the Reuse Request this negotiation step belongs to.

terms

The URI of the Reuse Terms associated with this negotiation step.

Example Response

HTTP/1.1 201 Created
Location: http://localhost:8080/reuseNegotiationSteps/865c415f-36c5-4fb1-b09b-edf81751e02e
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 804

{
  "id" : "865c415f-36c5-4fb1-b09b-edf81751e02e",
  "dateTime" : "2018-09-07T08:43:18.441Z",
  "message" : "I'd like to reuse your video",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/reuseNegotiationSteps/865c415f-36c5-4fb1-b09b-edf81751e02e"
    },
    "reuseNegotiationStep" : {
      "href" : "http://localhost:8080/reuseNegotiationSteps/865c415f-36c5-4fb1-b09b-edf81751e02e"
    },
    "creator" : {
      "href" : "http://localhost:8080/reuseNegotiationSteps/865c415f-36c5-4fb1-b09b-edf81751e02e/creator"
    },
    "request" : {
      "href" : "http://localhost:8080/reuseNegotiationSteps/865c415f-36c5-4fb1-b09b-edf81751e02e/request"
    },
    "terms" : {
      "href" : "http://localhost:8080/reuseNegotiationSteps/865c415f-36c5-4fb1-b09b-edf81751e02e/terms"
    }
  }
}

Reuse Request

Before creating a Reuse Request, some Reuse Terms and a Reuse Negotiation Step 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

negotiationSteps

Array

The URIs to the reuse negotiation steps of 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: 238

{"aboutVideo": "/uGVs/uXjFGmAMwpc","negotiationSteps": ["/reuseNegotiationSteps/ef51ae71-eada-428c-b2e9-dc8d8a50ff55"],"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","negotiationSteps": ["/reuseNegotiationSteps/ef51ae71-eada-428c-b2e9-dc8d8a50ff55"],"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 (JOURNALIST, OWNER, REJECTED or ACCEPTED)

notifyJournalist

Boolean

Indicates whether there is a pending notification to the journalist for this request

notifyOwner

Boolean

Indicates whether there is a pending notification to the owner for this request

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

negotiationSteps

The URI to the array of reuse negotiation steps of this Reuse Request

Example Response

HTTP/1.1 201 Created
Location: http://localhost:8080/reuseRequests/97912b84-c52a-4a3a-ab1c-4d9e957a0287
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 994

{
  "id" : "97912b84-c52a-4a3a-ab1c-4d9e957a0287",
  "dateTime" : "2018-09-07T08:43:15.645Z",
  "status" : "OWNER",
  "notifyOwner" : true,
  "notifyJournalist" : false,
  "lastStatusChange" : "2018-09-07T08:43:15.635Z",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/reuseRequests/97912b84-c52a-4a3a-ab1c-4d9e957a0287"
    },
    "reuseRequest" : {
      "href" : "http://localhost:8080/reuseRequests/97912b84-c52a-4a3a-ab1c-4d9e957a0287"
    },
    "aboutVideo" : {
      "href" : "http://localhost:8080/reuseRequests/97912b84-c52a-4a3a-ab1c-4d9e957a0287/aboutVideo"
    },
    "negotiationSteps" : {
      "href" : "http://localhost:8080/reuseRequests/97912b84-c52a-4a3a-ab1c-4d9e957a0287/negotiationSteps"
    },
    "createdBy" : {
      "href" : "http://localhost:8080/reuseRequests/97912b84-c52a-4a3a-ab1c-4d9e957a0287/createdBy"
    },
    "agreedBy" : {
      "href" : "http://localhost:8080/reuseRequests/97912b84-c52a-4a3a-ab1c-4d9e957a0287/agreedBy"
    }
  }
}

Cancel Reuse Agreement

Once a journalist and a content owner have arrived to an agreement, a Reuse Agreement is created. Nonetheless, the journalist will be free to cancel it whenever they like. This will be done through a PATCH to update the Reuse Agreement and set it to canceled.

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

canceled

String

Indicates the intention to cancel the agreement.

Example Request

PATCH /reuseAgreements/baf30466-d7be-490b-9850-94cfa55e48ea HTTP/1.1
Content-Type: application/json
Accept: application/hal+json
Authorization: Bearer INVID_VALID_TOKEN
Host: localhost:8080
Content-Length: 20

{"canceled": "true"}
$ curl 'http://localhost:8080/reuseAgreements/baf30466-d7be-490b-9850-94cfa55e48ea' -i -X PATCH -H 'Content-Type: application/json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer INVID_VALID_TOKEN' -d '{"canceled": "true"}'
Response

Response Headers

Name Description

Content-Type

The Content-Type of the payload

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

canceled

Boolean

Indicates whether this agreement has been canceled

_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

what

The URIs of the agreed Reuse Terms

who

The URIs of the agents agreeing

Example Response

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

{
  "id" : "baf30466-d7be-490b-9850-94cfa55e48ea",
  "dateTime" : "2018-09-07T08:43:54.472Z",
  "canceled" : true,
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/reuseAgreements/baf30466-d7be-490b-9850-94cfa55e48ea"
    },
    "reuseAgreement" : {
      "href" : "http://localhost:8080/reuseAgreements/baf30466-d7be-490b-9850-94cfa55e48ea"
    },
    "agrees" : {
      "href" : "http://localhost:8080/reuseAgreements/baf30466-d7be-490b-9850-94cfa55e48ea/agrees"
    },
    "who" : {
      "href" : "http://localhost:8080/reuseAgreements/baf30466-d7be-490b-9850-94cfa55e48ea/who"
    },
    "what" : {
      "href" : "http://localhost:8080/reuseAgreements/baf30466-d7be-490b-9850-94cfa55e48ea/what"
    }
  }
}

Reuse Template

A Reuse Template 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 Template can be defined for the whole Organization or only for himself.

In order to create a Reuse Template, it is required to firstly create its Reuse Terms. In this case, these will be instances of ReuseTemplateTerms, class that contains an additional field 'duration'. After that, these terms must be associated with a ReuseTemplate.

Additionally, there are some pre-defined default templates which applies for all users. These default templates are for "Make Available", "Broadcast" and both of them.

Reuse Template Term

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 Template Term refers to, like 'Make Available' or 'Broadcast'

scope

String

The scope to which the Reuse Term applies. This field have three possible values: UGV, ExternalUser and ContentOwner

who

Array

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

duration

String

Since it doesn’t make sense defining the begin and end dates on a template, we store the duration instead

where

String

Countries where the Reuse Template Term applies

with

String

Tool or instrument with which the Reuse Template Term applies

why

String

Reason for requesting the Reuse Template Term

how

String

How the content will be reused

conditions

String

Attribution message for this specific ReuseTerm

postconditions

String

Postconditions to fulfil after reusing the content

Example Request

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

{ "action": "Make Available","scope": "UGV","who": ["/organizations/7dcb0c88-9e8a-4d97-99d3-f25fa3c08514"],"duration": "P5M","where": "Spain","with": "TV","why": "To broadcast it on TV news","how": "Broadcast on TV","conditions": "Video from InVID retrieved from their YouTube channel","postconditions": "No Post Condition"}
$ curl 'http://localhost:8080/reuseTemplateTerms' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer INVID_VALID_TOKEN' -d '{ "action": "Make Available","scope": "UGV","who": ["/organizations/7dcb0c88-9e8a-4d97-99d3-f25fa3c08514"],"duration": "P5M","where": "Spain","with": "TV","why": "To broadcast it on TV news","how": "Broadcast on TV","conditions": "Video from InVID retrieved from their YouTube channel","postconditions": "No Post Condition"}'
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 Template Term

action

String

Reuse action(s) the Reuse Template Term refers to, like 'Make Available' or 'Broadcast'

scope

String

The scope to which the Reuse Term applies. This field have three possible values: UGV, ExternalUser and ContentOwner

duration

String

The duration of the template

where

String

Countries where the Reuse Template Term applies

with

String

Tool or instrument with which the Reuse Template Term applies

why

String

Reason for requesting the Reuse Template Term

how

String

How the content will be reused

conditions

String

Attribution message for this specific ReuseTemplateTerm

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

reuseTemplateTerm

The URI of the resource

who

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

forTemplate

The URI of the ReuseTemplate to which this ReuseTemplateTerm is associated

Example Response

HTTP/1.1 201 Created
Location: http://localhost:8080/reuseTemplateTerms/1a25461c-9b6f-4fbe-8d0f-27443b23a7d5
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1056

{
  "id" : "1a25461c-9b6f-4fbe-8d0f-27443b23a7d5",
  "action" : "Make Available",
  "when" : null,
  "endDate" : null,
  "where" : "Spain",
  "with" : "TV",
  "why" : "To broadcast it on TV news",
  "how" : "Broadcast on TV",
  "conditions" : "Video from InVID retrieved from their YouTube channel",
  "postconditions" : "No Post Condition",
  "scope" : "UGV",
  "what" : null,
  "duration" : "P5M",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/reuseTemplateTerms/1a25461c-9b6f-4fbe-8d0f-27443b23a7d5"
    },
    "reuseTemplateTerm" : {
      "href" : "http://localhost:8080/reuseTemplateTerms/1a25461c-9b6f-4fbe-8d0f-27443b23a7d5"
    },
    "requestUGV" : {
      "href" : "http://localhost:8080/reuseTemplateTerms/1a25461c-9b6f-4fbe-8d0f-27443b23a7d5/requestUGV"
    },
    "who" : {
      "href" : "http://localhost:8080/reuseTemplateTerms/1a25461c-9b6f-4fbe-8d0f-27443b23a7d5/who"
    },
    "forTemplate" : {
      "href" : "http://localhost:8080/reuseTemplateTerms/1a25461c-9b6f-4fbe-8d0f-27443b23a7d5/forTemplate"
    }
  }
}

Reuse Template

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

name

String

Name to identify the template

terms

Array

URI(s) of the ReuseTemplateTerm(s) defining this template

Example Request

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

{"name": "MyTemplate","terms": ["/reuseTemplateTerms/606cae3c-fd77-4fb8-a06b-4de2b8560533"]}
$ curl 'http://localhost:8080/reuseTemplates' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer INVID_VALID_TOKEN' -d '{"name": "MyTemplate","terms": ["/reuseTemplateTerms/606cae3c-fd77-4fb8-a06b-4de2b8560533"]}'
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 Template

name

String

Name to identify the template

_links

Object

Links to related resources detailed in the next table

Response Links

Relation Description

self

The URI of the resource

reuseTemplate

The URI of the resource

terms

URI(s) of the ReuseTemplateTerm(s) defining this template

definedBy

The URI of the InVID User who defined this template

Example Response

HTTP/1.1 201 Created
Location: http://localhost:8080/reuseTemplates/d5451d13-66f6-4963-881e-1252538aa8bf
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 578

{
  "id" : "d5451d13-66f6-4963-881e-1252538aa8bf",
  "name" : "MyTemplate",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/reuseTemplates/d5451d13-66f6-4963-881e-1252538aa8bf"
    },
    "reuseTemplate" : {
      "href" : "http://localhost:8080/reuseTemplates/d5451d13-66f6-4963-881e-1252538aa8bf"
    },
    "definedBy" : {
      "href" : "http://localhost:8080/reuseTemplates/d5451d13-66f6-4963-881e-1252538aa8bf/definedBy"
    },
    "terms" : {
      "href" : "http://localhost:8080/reuseTemplates/d5451d13-66f6-4963-881e-1252538aa8bf/terms"
    }
  }
}

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.eyJzdWIiOiJ1c2VyIiwianRpIjoiZDhkMWYxYmItMjMwNi00MmQ1LTlhNDMtMDM2YzY4YjlmZTlkIiwiZW1haWwiOiJ1c2VyQGdtYWlsLmNvbSIsInNjb3BlcyI6WyJST0xFX0NPTlRFTlRfT1dORVIiXSwiaXNzIjoiaW52aWQiLCJpYXQiOjE1MzYzMDk4MDYsImV4cCI6MTU0NDE3MjIwNn0.Q0HExhOT3Al1EL3hA62oITkEownjpBY61ujZxGIsi99U71GkD7jGESR7r2j_2ngGdHdlRbb2NByjqquvhAeLYQ

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.eyJzdWIiOiJ1c2VyIiwianRpIjoiODgxZTQ0YTUtZDEwZi00MDRjLWE2OWYtMzlkNDYzZDY3MWFhIiwiZW1haWwiOiJ1c2VyQGZhY2Vib29rLmNvbSIsInNjb3BlcyI6WyJST0xFX0NPTlRFTlRfT1dORVIiXSwiaXNzIjoiaW52aWQiLCJpYXQiOjE1MzYzMDk4NDUsImV4cCI6MTU0NDE3MjI0NX0.IPDw6K84mN715wHhst4gUIsdekBj3lEAPNQXHsNwyriu0p1MeZHHExZhUZSVESKkGZprdhY9jxjFWbwIl2INjw

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.eyJzdWIiOiJ1c2VyIiwianRpIjoiNGIxM2NkODQtZGVhMS00Y2NkLTg3MzYtYzU1MWE4MzIzOGJkIiwiZW1haWwiOiJ1c2VyQHR3aXR0ZXIuY29tIiwic2NvcGVzIjpbIlJPTEVfQ09OVEVOVF9PV05FUiJdLCJpc3MiOiJpbnZpZCIsImlhdCI6MTUzNjMwOTgzMSwiZXhwIjoxNTQ0MTcyMjMxfQ.yqodGzQrwhxNoGHaBnbpoZgPV6cIcUtqtyJk_YniyCT5398lam58jEHgCE1R8GeBctcoKtvuYHFZVzzwUBrQ8A

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.eyJzdWIiOiJ1c2VyIiwianRpIjoiMTQzODMzNWEtY2NlNS00NjY5LTk4MTgtZTJlZDJiNTVmZDNmIiwiZW1haWwiOiJ1c2VyQGdtYWlsLmNvbSIsInNjb3BlcyI6WyJST0xFX0NPTlRFTlRfT1dORVIiXSwiaXNzIjoiaW52aWQiLCJpYXQiOjE1MzYzMDk4MjUsImV4cCI6MTU0NDE3MjIyNX0.ymFHAJ4FLHLjt7m9ylQQhF7Wtm8r_OQG2UFhmbVWPqArKYpY2iihzYEHP-iYCXQaIQSIYZvJQ3RSxRmfQcMxPg
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.eyJzdWIiOiJ1c2VyIiwianRpIjoiMTQzODMzNWEtY2NlNS00NjY5LTk4MTgtZTJlZDJiNTVmZDNmIiwiZW1haWwiOiJ1c2VyQGdtYWlsLmNvbSIsInNjb3BlcyI6WyJST0xFX0NPTlRFTlRfT1dORVIiXSwiaXNzIjoiaW52aWQiLCJpYXQiOjE1MzYzMDk4MjUsImV4cCI6MTU0NDE3MjIyNX0.ymFHAJ4FLHLjt7m9ylQQhF7Wtm8r_OQG2UFhmbVWPqArKYpY2iihzYEHP-iYCXQaIQSIYZvJQ3RSxRmfQcMxPg' -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.eyJzdWIiOiJ1c2VyIiwianRpIjoiN2QwNDhiZjAtYTFmMy00YTFiLTk0ZWYtMWY5YTBlMjk3OGMwIiwiZW1haWwiOiJ1c2VyQGdtYWlsLmNvbSIsInNjb3BlcyI6WyJST0xFX0NPTlRFTlRfT1dORVIiXSwiaXNzIjoiaW52aWQiLCJpYXQiOjE1MzYzMDk4NjAsImV4cCI6MTU0NDE3MjI2MH0.7RqdCANZURSXjNJVh-2Hm0PhocBoT5LFYtiyRKFCTI_MvJ89vz9vPAcDPrzMtK44ENt4PLjK3Lyc-Wt_3ZqnlA
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.eyJzdWIiOiJ1c2VyIiwianRpIjoiN2QwNDhiZjAtYTFmMy00YTFiLTk0ZWYtMWY5YTBlMjk3OGMwIiwiZW1haWwiOiJ1c2VyQGdtYWlsLmNvbSIsInNjb3BlcyI6WyJST0xFX0NPTlRFTlRfT1dORVIiXSwiaXNzIjoiaW52aWQiLCJpYXQiOjE1MzYzMDk4NjAsImV4cCI6MTU0NDE3MjI2MH0.7RqdCANZURSXjNJVh-2Hm0PhocBoT5LFYtiyRKFCTI_MvJ89vz9vPAcDPrzMtK44ENt4PLjK3Lyc-Wt_3ZqnlA' -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.eyJzdWIiOiJ1c2VyIiwianRpIjoiMzE4NzczNmYtZjU5Yy00NjFjLWIzMDgtOTdkNGVjMTFjOWQyIiwiZW1haWwiOiJ1c2VyQGdtYWlsLmNvbSIsInNjb3BlcyI6WyJST0xFX0NPTlRFTlRfT1dORVIiXSwiaXNzIjoiaW52aWQiLCJpYXQiOjE1MzYzMDk4MzcsImV4cCI6MTU0NDE3MjIzN30._mMWHF24DeELpBmZEd_favHWv-JcmnJT5xfSWdct9DZRgNYdJBGkPm3WKBytefk-ARVQqAoVnIg301eG_54CzA
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.eyJzdWIiOiJ1c2VyIiwianRpIjoiMzE4NzczNmYtZjU5Yy00NjFjLWIzMDgtOTdkNGVjMTFjOWQyIiwiZW1haWwiOiJ1c2VyQGdtYWlsLmNvbSIsInNjb3BlcyI6WyJST0xFX0NPTlRFTlRfT1dORVIiXSwiaXNzIjoiaW52aWQiLCJpYXQiOjE1MzYzMDk4MzcsImV4cCI6MTU0NDE3MjIzN30._mMWHF24DeELpBmZEd_favHWv-JcmnJT5xfSWdct9DZRgNYdJBGkPm3WKBytefk-ARVQqAoVnIg301eG_54CzA' -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.eyJzdWIiOiJ1c2VyIiwianRpIjoiMjJkMTlkNTItYWI0Yy00MWQ0LTgwODUtZmYxMTNhNzI2Y2E5IiwiZW1haWwiOiJ1c2VyQGdtYWlsLmNvbSIsInNjb3BlcyI6WyJST0xFX0NPTlRFTlRfT1dORVIiXSwiaXNzIjoiaW52aWQiLCJpYXQiOjE1MzYzMDk4NjcsImV4cCI6MTU0NDE3MjI2N30.z7DFYAQY3b48ISt0AEzhPStOkhpjt6I1bT8EKTKwBn659cd0pxIeLJA9B7yo9yk3BCIoKt0eyXp0tSZNXSQcsQ
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.eyJzdWIiOiJ1c2VyIiwianRpIjoiMjJkMTlkNTItYWI0Yy00MWQ0LTgwODUtZmYxMTNhNzI2Y2E5IiwiZW1haWwiOiJ1c2VyQGdtYWlsLmNvbSIsInNjb3BlcyI6WyJST0xFX0NPTlRFTlRfT1dORVIiXSwiaXNzIjoiaW52aWQiLCJpYXQiOjE1MzYzMDk4NjcsImV4cCI6MTU0NDE3MjI2N30.z7DFYAQY3b48ISt0AEzhPStOkhpjt6I1bT8EKTKwBn659cd0pxIeLJA9B7yo9yk3BCIoKt0eyXp0tSZNXSQcsQ' -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.eyJzdWIiOiJ1c2VyIiwianRpIjoiNzg3MDkyZWMtYzNlOC00ZDAzLWJmOGItNDBiODI1NjE2NjU5IiwiZW1haWwiOiJ1c2VyQHR3aXR0ZXIuY29tIiwic2NvcGVzIjpbIlJPTEVfQ09OVEVOVF9PV05FUiJdLCJpc3MiOiJpbnZpZCIsImlhdCI6MTUzNjMwOTg0OCwiZXhwIjoxNTQ0MTcyMjQ4fQ.0bL7cXGlLFruNc54qMzzeDUKSOG3OD-RZ3nZXaOX74_MHUBaRxHqOtVhvV4SfFuR8UlXTGMLPodI-HuZ4GOv2g

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.eyJzdWIiOiJ1c2VyIiwianRpIjoiOTA5ZDQ3OGYtNDgyMi00YzE3LWI2ZjctN2YyMjQ2NDdjYmEzIiwiZW1haWwiOiJ1c2VyQGdtYWlsLmNvbSIsInNjb3BlcyI6WyJST0xFX0NPTlRFTlRfT1dORVIiXSwiaXNzIjoiaW52aWQiLCJpYXQiOjE1MzYzMDk4MjIsImV4cCI6MTU0NDE3MjIyMn0.lhoG_a3sAxPYAAHi_lWTUTajKlu4QJHhLd5uYSa9OC1Tio4dEEdTYUHlPneaDLWwnnHJHWncyA_NM91kY8NQhw
Host: localhost:8080
$ curl 'http://localhost:8080/reuseRequests' -i -H 'Accept: application/hal+json' -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ1c2VyIiwianRpIjoiOTA5ZDQ3OGYtNDgyMi00YzE3LWI2ZjctN2YyMjQ2NDdjYmEzIiwiZW1haWwiOiJ1c2VyQGdtYWlsLmNvbSIsInNjb3BlcyI6WyJST0xFX0NPTlRFTlRfT1dORVIiXSwiaXNzIjoiaW52aWQiLCJpYXQiOjE1MzYzMDk4MjIsImV4cCI6MTU0NDE3MjIyMn0.lhoG_a3sAxPYAAHi_lWTUTajKlu4QJHhLd5uYSa9OC1Tio4dEEdTYUHlPneaDLWwnnHJHWncyA_NM91kY8NQhw'

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 (JOURNALIST, OWNER, REJECTED or ACCEPTED)

_embedded.reuseRequests.[].notifyJournalist

Boolean

Indicates whether there is a pending notification to the journalist for this request

_embedded.reuseRequests.[].notifyOwner

Boolean

Indicates whether there is a pending notification to the owner for this request

_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: 1559

{
  "_embedded" : {
    "reuseRequests" : [ {
      "id" : "b7a35612-07d5-4e5f-b8c4-a8d56805b1be",
      "dateTime" : "2018-09-07T08:43:42.79Z",
      "status" : "OWNER",
      "notifyOwner" : false,
      "notifyJournalist" : false,
      "lastStatusChange" : "2018-09-07T08:43:42.79Z",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/reuseRequests/b7a35612-07d5-4e5f-b8c4-a8d56805b1be"
        },
        "reuseRequest" : {
          "href" : "http://localhost:8080/reuseRequests/b7a35612-07d5-4e5f-b8c4-a8d56805b1be"
        },
        "createdBy" : {
          "href" : "http://localhost:8080/reuseRequests/b7a35612-07d5-4e5f-b8c4-a8d56805b1be/createdBy"
        },
        "negotiationSteps" : {
          "href" : "http://localhost:8080/reuseRequests/b7a35612-07d5-4e5f-b8c4-a8d56805b1be/negotiationSteps"
        },
        "agreedBy" : {
          "href" : "http://localhost:8080/reuseRequests/b7a35612-07d5-4e5f-b8c4-a8d56805b1be/agreedBy"
        },
        "aboutVideo" : {
          "href" : "http://localhost:8080/reuseRequests/b7a35612-07d5-4e5f-b8c4-a8d56805b1be/aboutVideo"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/reuseRequests{?page,size,sort}",
      "templated" : true
    },
    "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.eyJzdWIiOiJ1c2VyIiwianRpIjoiYmNmZjk3MzctMDE0ZS00YjE2LWFkMjUtMDdhOWEzMWM3NTY2IiwiZW1haWwiOiJ1c2VyQGdtYWlsLmNvbSIsInNjb3BlcyI6WyJST0xFX0NPTlRFTlRfT1dORVIiXSwiaXNzIjoiaW52aWQiLCJpYXQiOjE1MzYzMDk4NzMsImV4cCI6MTU0NDE3MjI3M30.7mLu3Tg2ZDpDFydw198I-U0C7R2PN4gmTUamIk2lrHhUw56Ij3C-uvluYzA2lJMpGRy1HM23wxxQQ14LJsbcDA
Host: localhost:8080
Content-Length: 65

{"agrees": "/reuseRequests/0231ab51-39f4-4f76-a75e-4ed50949e209"}
$ curl 'http://localhost:8080/reuseAgreements' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ1c2VyIiwianRpIjoiYmNmZjk3MzctMDE0ZS00YjE2LWFkMjUtMDdhOWEzMWM3NTY2IiwiZW1haWwiOiJ1c2VyQGdtYWlsLmNvbSIsInNjb3BlcyI6WyJST0xFX0NPTlRFTlRfT1dORVIiXSwiaXNzIjoiaW52aWQiLCJpYXQiOjE1MzYzMDk4NzMsImV4cCI6MTU0NDE3MjI3M30.7mLu3Tg2ZDpDFydw198I-U0C7R2PN4gmTUamIk2lrHhUw56Ij3C-uvluYzA2lJMpGRy1HM23wxxQQ14LJsbcDA' -d '{"agrees": "/reuseRequests/0231ab51-39f4-4f76-a75e-4ed50949e209"}'

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

canceled

Boolean

Indicates whether this agreement has been canceled

_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

what

The URIs of the agreed Reuse Terms

who

The URIs of the agents agreeing

Example Response

HTTP/1.1 201 Created
Location: http://localhost:8080/reuseAgreements/a3094304-12b1-479b-b08e-549d996b27ce
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 732

{
  "id" : "a3094304-12b1-479b-b08e-549d996b27ce",
  "dateTime" : "2018-09-07T08:44:33.395Z",
  "canceled" : false,
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/reuseAgreements/a3094304-12b1-479b-b08e-549d996b27ce"
    },
    "reuseAgreement" : {
      "href" : "http://localhost:8080/reuseAgreements/a3094304-12b1-479b-b08e-549d996b27ce"
    },
    "what" : {
      "href" : "http://localhost:8080/reuseAgreements/a3094304-12b1-479b-b08e-549d996b27ce/what"
    },
    "agrees" : {
      "href" : "http://localhost:8080/reuseAgreements/a3094304-12b1-479b-b08e-549d996b27ce/agrees"
    },
    "who" : {
      "href" : "http://localhost:8080/reuseAgreements/a3094304-12b1-479b-b08e-549d996b27ce/who"
    }
  }
}

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/8bb6a987-28c6-478e-bb8a-78f107b7a30a HTTP/1.1
Content-Type: application/json
Accept: application/hal+json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ1c2VyIiwianRpIjoiMTFmMTQxMDItMzlmZC00ODA1LWIwMzItNWE5NmVjMzVjODM2IiwiZW1haWwiOiJ1c2VyQGdtYWlsLmNvbSIsInNjb3BlcyI6WyJST0xFX0NPTlRFTlRfT1dORVIiXSwiaXNzIjoiaW52aWQiLCJpYXQiOjE1MzYzMDk4MDksImV4cCI6MTU0NDE3MjIwOX0.UmdZgFOiXC62FnTOSvKy_fnCrtyu3PLl8WOMuWpz5kXu1-RJEmVK_UWrVTn80zhUoWdfuNJyic59MFIroFcTzA
Host: localhost:8080
Content-Length: 22

{"status": "REJECTED"}
$ curl 'http://localhost:8080/reuseRequests/8bb6a987-28c6-478e-bb8a-78f107b7a30a' -i -X PATCH -H 'Content-Type: application/json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ1c2VyIiwianRpIjoiMTFmMTQxMDItMzlmZC00ODA1LWIwMzItNWE5NmVjMzVjODM2IiwiZW1haWwiOiJ1c2VyQGdtYWlsLmNvbSIsInNjb3BlcyI6WyJST0xFX0NPTlRFTlRfT1dORVIiXSwiaXNzIjoiaW52aWQiLCJpYXQiOjE1MzYzMDk4MDksImV4cCI6MTU0NDE3MjIwOX0.UmdZgFOiXC62FnTOSvKy_fnCrtyu3PLl8WOMuWpz5kXu1-RJEmVK_UWrVTn80zhUoWdfuNJyic59MFIroFcTzA' -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

notifyJournalist

Boolean

Indicates whether there is a pending notification to the journalist for this request

notifyOwner

Boolean

Indicates whether there is a pending notification to the owner for this request

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

negotiationSteps

The URI to the array of reuse negotiation steps of this Reuse Request

Example Response

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

{
  "id" : "8bb6a987-28c6-478e-bb8a-78f107b7a30a",
  "dateTime" : "2018-09-07T08:43:29.629Z",
  "status" : "REJECTED",
  "notifyOwner" : false,
  "notifyJournalist" : false,
  "lastStatusChange" : "2018-09-07T08:43:29.677Z",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/reuseRequests/8bb6a987-28c6-478e-bb8a-78f107b7a30a"
    },
    "reuseRequest" : {
      "href" : "http://localhost:8080/reuseRequests/8bb6a987-28c6-478e-bb8a-78f107b7a30a"
    },
    "aboutVideo" : {
      "href" : "http://localhost:8080/reuseRequests/8bb6a987-28c6-478e-bb8a-78f107b7a30a/aboutVideo"
    },
    "negotiationSteps" : {
      "href" : "http://localhost:8080/reuseRequests/8bb6a987-28c6-478e-bb8a-78f107b7a30a/negotiationSteps"
    },
    "agreedBy" : {
      "href" : "http://localhost:8080/reuseRequests/8bb6a987-28c6-478e-bb8a-78f107b7a30a/agreedBy"
    },
    "createdBy" : {
      "href" : "http://localhost:8080/reuseRequests/8bb6a987-28c6-478e-bb8a-78f107b7a30a/createdBy"
    }
  }
}

Retrieve data

In a platform like this, all users must be able to retrieve the information stored about them. For this reason, we provide endpoints to retrieve this data. For a better format of the data, we have divided it into the following parts:

  • ExternalUsers and its associated UGVs

  • ReuseRequests and everything related to them (ReuseNegotiationSteps, InVIDInvites, ReuseTerms and ReuseAgreements

  • ReuseTemplates and its associated ReuseTemplateTerms

  • User and Organization (in the case of InVIDUsers)

Additionally, we also offer the possibility to retrieve all the data in a single call. However, since the amount of data may be quite big, this will be sent by email in an attached file in JSON format.

Domain Model

jdot

Send feedback

In order to give some feedback about the platform, anyone can send it and an email will be sent to the administrators of the InVID Project.

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

email

String

The email provided by the submitter of the feedback

message

String

The message of the feedback

Example Request

POST /feedback HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: localhost:8080
Content-Length: 74

{"message":"I really like this platform.","email":"test@invid-project.eu"}
$ curl 'http://localhost:8080/feedback' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{"message":"I really like this platform.","email":"test@invid-project.eu"}'