Work.register

From Safe Creative API
Revision as of 11:26, 20 April 2022 by Adminwiki (talk | contribs) (→‎Example)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

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
  • editlocked: For partners, user will not be able to edit the work through Safe Creative web
  • metaN: (multivalue) Meta data for works in JSON formmat. Eg: { "nsterm" : "dc:title" , "value": "Star 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.

Metadata for audiovisual works

Audiovisual works (work types: ffilm, mfilm, sfilm, tvfilm, serial, telenovela, other) should be registered with their supported metadata tags to have a fully informed registration. For these type of works it's not necessary to provide a file or url for registration. If no file is provided, a text file with the work metadata information is automatically generated and used as evidence of registration.

Metadata tags are provided in metadataN params as JSON values. Each JSON value has the following structure: 

{"nsterm": "metadata tag name", "value": "metadata tag value" }

Some tags include additional attributes in an attrs field. E.g.: 

{"nsterm": "dc:title", "value": "English title", "attrs": { "xml:lang": "en" }}

Some tags, such as dc:title, rol:actor,... may be repeated to support multiple titles, actors, etc.

These are the supported metadata tags for audiovisual works. Required tags are marked with an asterisk (*).

  • dc:title Alternative title (can be repeated)
    • Must have an attribute xml:lang with the language of the title (ISO language code)
  • dc:abstract* Abstract or synopsis
  • xsd:gYear* Year of creation
  • dc:extent* Duration in seconds
  • gn:country Country of production (ISO code - can be repeated)
  • rol:director* Film director (can be repeated)
  • rol:producer Film producer (can be repeated)
  • rol:actor Actor/actress (can be repeated)
  • rol:screenwriter Screenwriter (can be repeated)
  • rol:composer Music composer (can be repeated)
  • rol:directorOfPhotography Director of photography (can be repeated)
  • rol:photographer Photographer (can be repeated)
  • rol:designer Designer (can be repeated)
  • rol:contributor Other film crew (can be repeated)
  • sc:color Color film (true|false)
  • sc:sound Film with sound (true|false)
  • sc:chapters Number of chapters (for serial and telenovela work types)

Returns

  • workregistry
    • code: Code of the registered work

Example

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>
Retrieved from "https://www.safecreative.org/mw/index.php?title=Work.register&oldid=822"