Work.register: Difference between revisions

From Safe Creative API
Jump to navigation Jump to search
w>Jguillo
No edit summary
w>Jguillo
No edit summary
Line 56: Line 56:


== For copyright info providers ==
== 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
* '''userinformer:''' 1 to register the work as a copyright info provider
* '''authorfirstname''N'':''' first names or work author(s)
* '''authorfirstname''N'':''' first names or work author(s)

Revision as of 13:17, 20 May 2010

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)
  • 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.
  • editlocked: For partners, user will not be able to edit the work through Safe Creative web
  • worktype: Work type code (see work.types)
  • 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
  • obs: extra private notes for the work
  • 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
  • final: 1 if you want the work to be left in REGISTERED state and not PREREGISTERED
  • meta: 1 if the registration is not a fully legal work registration. Please do not use.
  • 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
  • authorfirstnameN: first names or work author(s)
  • authormiddlenameN: middle names or work author(s)
  • authorlastnameN: last names or work author(s)
  • rightsholderfirstnameN: first names or work rights holder(s)
  • rightsholdermiddlenameN: middle names or work rights holder(s)
  • rightsholderlastnameN: last names or work rights holder(s)

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.

Registration profile is applied first, if no profile is specified then the user default profile is applied. The rest of the specified parameters replace the values of the profile.

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>