Work.register: Difference between revisions

From Safe Creative API
Jump to navigation Jump to search
w>Ddesola
w>Ddesola
Line 53: Line 53:
* '''meta:''' 1 if the registration is not a fully legal work registration. Please do not use.
* '''meta:''' 1 if the registration is not a fully legal work registration. Please do not use.
* '''editlocked:''' For partners, user will not be able to edit the work through Safe Creative web
* '''editlocked:''' For partners, user will not be able to edit the work through Safe Creative web
* '''meta''N'':''' (multivalue) Meta data for av works. Eg: { "nsterm" : "dc:title" , "value": "Start Wars" , "attrs" : { "xml:lang" : "en" }}
* '''meta''N'':''' (multivalue) Meta data for works in JSON formmated. Eg: { "nsterm" : "dc:title" , "value": "Start Wars" , "attrs" : { "xml:lang" : "en" }}
* '''link''N'':''' (multivalue) Work external links, replace previous work links. Format is url|name|type where type can be DOWNLOAD or INFO. N must be 1..n
* '''link''N'':''' (multivalue) Work external links, replace previous work links. Format is url|name|type where type can be DOWNLOAD or INFO. N must be 1..n
* '''extralink''N'':''' (mutivalue) Work external links, to be added to the previously defined work links. Same format as ''linkN''
* '''extralink''N'':''' (mutivalue) Work external links, to be added to the previously defined work links. Same format as ''linkN''
Line 82: Line 82:


You can only use one of these methods at the same time.
You can only use one of these methods at the same time.
== For audiovisual works (work types: video, ffilm, format, mfilm, serial, sfilm, telenovela, tvfilm) this metadata are required ==
* '''xsd:gYear'''
* '''dc:extent'''
* '''rol:director'''
* '''dc:abstract'''


= Returns =
= Returns =

Revision as of 07:41, 31 January 2019

Registers or modifies a work.

Work content can be specified:

  • with an upload ticket obtained from a previous upload (see work.upload.lookup)
  • using a text request parameter
  • with an url where the work will be downloaded from

Using an upload ticket or text parameter are both synchronous registrations. You can register a work asynchronously using an url and sha-1 of the content. Safe Creative engine will download the content of the work to be registered. Work will be in PROCESSING state and will not be visible on the user's work list until it has been downloaded and registration is then finished. You will receive a callback when this happens.

If the code parameter is specified the work will be updated with the new data. If the work is in REGISTERED state, you cannot change the work title, alias, nor content. You cannot change the work content if you registered the work using asyncrhonous mode (register via url) and it has not been downloaded yet.

If you are a partner, you can register a work as a copyright information provider (or informer). The authorizing user will be registered as informer and you must provide the authors' and copyright holders' names (see How to: Register a work as a copyright info provider).

This call requires a nonce key

Info

  • Component name: work.register
  • Signature: Requires signature using the authkey's private key
  • Timestamp: Requires ztime parameter
  • Nonce key: Requires a nonce key
  • Authorization level:
    • ADD for registering a new work
    • MANAGE to modify an existing work
  • API trust level: Standard

Parameters

  • authkey*: Authorization key
  • ztime*: Z-Timestamp
  • noncekey*: nonce key
  • code: Code of the work you want to modify
  • title: Title of the work. If not specified, it will be taken from the work file name.
  • profile: Registration profile code (see user.profiles)
    • Registration profile is applied first, if no profile is specified then the user default profile is applied, if any.
    • The rest of the specified parameters replace the values of the profile.
  • excerpt: Work summary or description
  • license: Code of the license (see user.licenses) to apply to this work.
    • For new works, if no license nor profile is specified, work will be registered with all rights reserved.
  • worktype: Work type code (see work.types)
    • Required for new works if no profile is specified
  • language: Work language code (see work.languages)
  • tags: Comma-separated list of tags. When modifying a work, these will replace existing tags
  • extratags: Comma separated list of tags, to be added to existing tags
  • allowdownload: 1 when the work is publicly downloadable
  • registrypublic: 1 to make registration information public, 0 if registration is private.
  • usealias: 1 to register the work under a pseudonym
  • alias: pseudonym of the user to be asigned to the work
  • userauthor: 1 when the user is the work author
  • userrights: 1 when the user is a rights holder for the work
  • final: 1 if you want the work to be left in REGISTERED state and not PREREGISTERED
  • obs: extra private notes for the work
  • meta: 1 if the registration is not a fully legal work registration. Please do not use.
  • editlocked: For partners, user will not be able to edit the work through Safe Creative web
  • metaN: (multivalue) Meta data for works in JSON formmated. Eg: { "nsterm" : "dc:title" , "value": "Start Wars" , "attrs" : { "xml:lang" : "en" }}
  • linkN: (multivalue) Work external links, replace previous work links. Format is url|name|type where type can be DOWNLOAD or INFO. N must be 1..n
  • extralinkN: (mutivalue) Work external links, to be added to the previously defined work links. Same format as linkN
  • versionof: comma-separated list of work codes which the work is a version of. The specified works must exist and its state must be REGISTERED.
  • derivationof: comma-separated list of work codes which the work is derived from. The specified works must exist and its state must be REGISTERED.
  • compositionof: comma separated list of work codes which the work is composed of. The specified works must exist and its state must be REGISTERED.

For copyright info providers

See How to: Register a work as a copyright info provider for a complete example

  • userinformer: 1 to register the work as a copyright info provider
  • authorN: (multivalue) Full name of the work authors, as FirstName|MiddleName|LastName (middle name may be empty)
  • rightsholderN: (multivalue) Full name of the work rights holders, as FirstName|MiddleName|LastName (middle name may be empty)

Work content parameters

Option A: Register a text

  • text: text to be registered
  • filename: file name for the content to be used on downloads

Option B: Register a previously uploaded work

Option C: Register via url

  • url: URL of the file to be registered
  • filename: file name for the downloaded content
  • checksum: SHA-1 hash of the content to be downloaded
  • size: size in bytes of the content to be downloaded

You can only use one of these methods at the same time.

For audiovisual works (work types: video, ffilm, format, mfilm, serial, sfilm, telenovela, tvfilm) this metadata are required

  • xsd:gYear
  • dc:extent
  • rol:director
  • dc:abstract

Returns

  • workregistry
    • code: Code of the registered work

Example

REQUEST to get a nonce key

https://api.safecreative.org/v2/
?component=authkey.state
&authkey=1i5g2aaf2bz09lyo867cuimqg
&sharedkey=zy9x4ol0ctg3btyswq7b5wi9
&ztime=1271749829192
&signature=508333b024993bbe54261a8c6713767dfe3ec9b1

RESPONSE:

<?xml version="1.0" encoding="UTF-8"?>
<authkeystate>
  <authkey>1i5g2aaf2bz09lyo867cuimqg</authkey>
  <level>MANAGE</level>
  <noncekey>4vrghpn0n8jxrrvoi3b7zta1c</noncekey>
  <usercode>0907100000018</usercode>
  <authorized>true</authorized>
</authkeystate>


REQUEST:

https://api.safecreative.org/v2/
?component=work.register
&authkey=1i5g2aaf2bz09lyo867cuimqg
&allowdownload=1
&excerpt=An+important+text+about+registry+philosophy
&license=http%3A%2F%2Fcreativecommons.org%2Flicenses%2Fnc-sampling%2B%2F1.0%2F
&noncekey=4vrghpn0n8jxrrvoi3b7zta1c
&obs=More+info+at+%3Ca+href%3D%27http%3A%2F%2Fsafecreative.info%27%3Ehttp%3A%2F%2Fsafecreative.info%3C%2Fa%3E
&registrypublic=1
&tags=tag1%2C+tag2
&text=Text+to+be+registered
&title=My+first+registration
&usealias=1
&userauthor=1
&worktype=article
&ztime=1271749829429
&signature=0042020a7ffc118d189aa27a9b78d1962e781667

RESPONSE:

<?xml version="1.0" encoding="UTF-8"?>
<workregistry>
  <code>1004200146109</code>
</workregistry>