Navigation

Staging Version Documentation

Author:Nathan R. Yergler, John E. Doig III
Version:Staging
Updated:$Date: 2010-03-16 15:19:13 -0700 (Mon, 20 Jul 2009) $

This document covers the current staging release of CC Web Services. This should be considered unstable and only used for application testing and development. Production applications should use the current stable version, as the development API can and will change. Information on the curent version can be found at http://api.creativecommons.org.

The staging release is the result of an internal re-organization of the technical infrastructure at Creative Commons. The goal of the staging version of the CC Web Services is to provide an interface that is more uniform with various other tools made available by Creative Commons.

Access Method

The Creative Commons Web Services are accessible via a REST interface. The interface is rooted at http://api.creativecommons.org/rest/staging/.

Valid Calls

/locales

Returns an XML document detailing the available values which may be specified for locale in other calls. The returned document has the following format

<locales>
  <locale id="en_CA"/>
  <locale id="fr"/>

  ...
</locales>

A future development version may include labels for the locales if users desire it.

/[?locale=xx]

(synonym for /classes)

Returns an XML document describing the available license classes. A license class is a “family” of licenses. Current classes are standard (basic CC licenses), recombo (the Sampling licenses), zero (the CC0 waiver), mark (the Public Domain Mark), and publicdomain (now deprecated, aliased to the zero class). Classes may be added at any time in the future without breaking 1.0 compatibility.

A partial example of the returned document is:

<licenses>
    <license id="publicdomain">Public Domain</license>
    <license id="standard">Creative Commons</license>
    <license id="recombo">Sampling</license>
    <license id="zero">CC0</license>
    <license id="mark">Public Domain Mark</license>
</licenses>

If a value for locale is supplied, the service will attempt to return localized class descriptions. If not specified, English will be returned.

/license/<class>[?locale=xx]

Called with a license class id from the call above as <class>. Returns an XML document describing the list of fields which must be supplied in order to issue a license of the given class.

If a value for locale is supplied, the service will attempt to return localized labels and descriptions. If not specified, English will be returned.

A partial example of the returned document for http://api.creativecommons.org/rest/staging/license/standard

 <licenseclass id="standard">
  <label xml:lang="en">Creative Commons</label>
   <field id="commercial">
    <label xml:lang="en">Allow commercial uses of your work?</label>
    <description xml:lang="en">The licensor permits others to copy, distribute and transmit the work. In return, licensees may not use the work for commercial purposes — unless they get the licensor's permission.</description>
    <type>enum</type>
    <enum id="y">
     <label xml:lang="en">Yes</label>
     <description xml:lang="en">The licensor permits others to copy, distribute, display, and perform the work, including for commercial purposes.</description>
    </enum>
    <enum id="n">
     <label xml:lang="en">No</label>
     <description xml:lang="en">The licensor permits others to copy, distribute, display, and perform the work for non-commercial purposes only.</description>
    </enum>
  </field>
  <field id="derivatives">
   <label xml:lang="en">Allow modifications of your work?</label>
   <description xml:lang="en">The licensor permits others to copy, distribute and transmit only unaltered copies of the work — not derivative works based on it.</description>
   <type>enum</type>
   <enum id="y">
    <label xml:lang="en">Yes</label>
    <description xml:lang="en">The licensor permits others to copy, distribute, display and perform the work, as well as make derivative works based on it.</description>
   </enum>
   <enum id="sa">
    <label xml:lang="en">ShareAlike</label>
    <description xml:lang="en">The licensor permits others to distribute derivative works only under the same license or one compatible with the one that governs the licensor's work.</description>
   </enum>
   <enum id="n">
    <label xml:lang="en">No</label>
    <description xml:lang="en">The licensor permits others to copy, distribute and transmit only unaltered copies of the work — not derivative works based on it.</description>
   </enum>
  </field>
  <field id="jurisdiction">
   <label xml:lang="en">Jurisdiction of your license:</label>
   <description xml:lang="en">If you desire a license governed by the Copyright Law of a specific jurisdiction, please select the appropriate jurisdiction.</description>
   <type>enum</type>
   <enum id="">
    <label xml:lang="en">Generic</label>
   </enum>
   <enum id="at">
    <label xml:lang="en">Austria</label>
   </enum>
  </field>
</licenseclass>

Note that a given field or enum element may have more than one label, so long as they have unique xml:lang attributes. Future language translations may be added at any time in the future without breaking 1.0 compatibility.

/license/<class>/issue

Called with an HTTP POST whose contents are a single form variable, answers. The value of answers is an XML string containing values which match each field element found in the earlier /license/<class>[?locale=xx] call. A sample answers string for the previous example is:

<answers>
  <locale>en</locale>
  <license-standard>
    <commercial>n</commercial>
    <derivatives>y</derivatives>
    <jurisdiction></jurisdiction>
  </license-standard>
</answers>

This example would issue a by-nc license in the generic (default) jurisdiction.

<answers> XML syntax

The <answers> block is structured using the following rules:

  • The <locale> element is optional and specifies the language to use when localizing the license HTML and name. If omitted, English (US) will be used. See /locales for information on obtaining a list of valid locales.
  • The <license-standard> tag is the license class prepended with license-.
  • Each sub-element of <license-xxx> matches a field id, and the content of the elements matches the enum id for the selected choice. Only values specified as the id attribute for enum elements are accepted as values for each field. If other values are specified, the server will return an invalidanswer error.
  • The exception to this rule is the <jurisdiction> tag. If an unknown jurisdiction is specified, the web services will silently fall back to the generic jurisdiction.

Providing work information

The information passed to the licensing web service may be augmented with optional information about the work to be licensed. If included this information will be used in the returned RDF and RDFa. For example:

<answers>
  <locale>en</locale>
  <license-standard>
    <commercial>n</commercial>
    <derivatives>y</derivatives>
    <jurisdiction></jurisdiction>
  </license-standard>
  <work-info>
    <work-url>http://example.com/work</work-url>
    <title>The Title</title>
    <source-url>http://example.com/source</source-url>
    <type>Text</type>
    <year>2006</year>
    <description>A brief description...</description>
    <creator>John Q. Public</creator>
    <holder>John Q. Public</holder>
    <actor_href>http://example.com/actor</actor_href>
    <territory>US</territory>
    <attribution_url>http://example.com/attribution</attribution_url>
    <attribution_name>Example</attribution_name>
    <more_permissions_url>http://example.com/more_permissions</more_permissions_url>
  </work-info>
</answers>

The work-info element and all sub-elements are optional.

Only certain sub-elements will affect the Licenses’ RDFa formatting, the table below details how the elements are used in the RDFa formatting.

License class Additional Information RDFa property Valid work-info elements
standard Attribute work to name cc:attributionName attribution_name, creator, holder
Attribute work to URL cc:attributionURL attribution_url, work-url
Title of work dc:title title
Source work URL dc:source source-url
Format of the work dc:type type
More permissions URL cc:morePermissions more_permissions_url
zero,

publicdomain

 Your name dct:title attribution_name, creator, name
Your URL dct:publisher attribution_url, actor_href
Title of work dct:title title
Territory vcard:Country territory
mark Work name dct:title title
Author name dct:title of dct:creator author_title, attribution_name, name
Author URL dct:creator author_url, attribution_url
Identifying Individual or Organization name dct:title of dct:publisher curator_title
Identifying Individual or Organization URL dct:publisher curator_url

The “Additional Information” column represents fields that are made available via the license choosers at http://creativecommons.org/choose/, http://creativecommons.org/choose/zero/, and http://creativecommons.org/choose/mark/. These fields will have an effect on how the resulting License RDFa is structured. The work-info elements are listed in order of searching priority, i.e. in determining a value for RDFa inclusion, a work-info element will override the elements that follow it in the valid elements list.

Additional work-info details

type

The work type should be specified as a valid Dublin Core dc:type; common values are:

  • Text
  • StillImage
  • MovingImage
  • InteractiveResource
  • Sound

This may also be left blank, in which case no assertion about the work type will be included.

territory
Must be a valid, uppercased ISO 3166-1-alpha-2 country code. A list of available codes can be found here.

License return format

The issue method forms an XML document based on the parameters provided by the answers xml. The result of this sample call would be an XML document, such as:

<?xml version="1.0" encoding="utf-8"?>
<result>
 <license-uri>http://creativecommons.org/licenses/by/3.0/us/</license-uri>
 <license-name>Attribution 3.0 United States</license-name>
 <deprecated>false</deprecated>
 <rdf>
   <rdf:RDF xmlns="http://creativecommons.org/ns#" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#">
    <Work rdf:about="">
     <license rdf:resource="http://creativecommons.org/licenses/by/3.0/us/"/>
    </Work>

    <License rdf:about="http://creativecommons.org/licenses/by/3.0/us/">
     <permits rdf:resource="http://creativecommons.org/ns#Reproduction"/>
     <permits rdf:resource="http://creativecommons.org/ns#Distribution"/>
     <requires rdf:resource="http://creativecommons.org/ns#Notice"/>
     <requires rdf:resource="http://creativecommons.org/ns#Attribution"/>
     <permits rdf:resource="http://creativecommons.org/ns#DerivativeWorks"/>
    </License>
   </rdf:RDF>
 </rdf>
 <licenserdf>
  <rdf:RDF xmlns="http://creativecommons.org/ns#" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
   <License rdf:about="http://creativecommons.org/licenses/by/3.0/us/">
     <permits rdf:resource="http://creativecommons.org/ns#Reproduction"/>
     <permits rdf:resource="http://creativecommons.org/ns#Distribution"/>
     <requires rdf:resource="http://creativecommons.org/ns#Notice"/>
     <requires rdf:resource="http://creativecommons.org/ns#Attribution"/>
     <permits rdf:resource="http://creativecommons.org/ns#DerivativeWorks"/>
   </License>
  </rdf:RDF>
 </licenserdf>
 <html><a rel="license" href="http://creativecommons.org/licenses/by/3.0/us/"><img alt="Creative Commons License" style="border-width:0" src="http://i.creativecommons.org/l/by/3.0/us/88x31.png"/></a><br/>This <span xmlns:dc="http://purl.org/dc/elements/1.1/" href="http://purl.org/dc/dcmitype/" rel="dc:type">work</span> is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/3.0/us/">Creative Commons Attribution 3.0 United States License</a>.</html>
</result>

Note the <html> element contains the HTML as generated by the CC License Chooser, including machine readable RDFa.

/license/<class>/get?

Called with an HTTP GET and a query string containing a parameter for each field specified in the previous call to /license/<class>[?locale=xx] The value of each parameter should match one of the enum values provided.

For example, a call to retrieve a Creative Commons standard license might look like:

/license/standard/get?commercial=n&derivatives=y&jurisdiction=

This example would issue a by-nc license in the generic (default) jurisdiction. The guidelines regarding <answers> XML syntax apply to the parameters on the querystring.

The XML returned from this call is identical to the return from /license/<class>/issue.

/details?license-uri=[uri]

Called with an HTTP POST or GET with a single form variable, license-uri. The value of license-uri is the URI of an existing Creative Commons license. The call returns the same result as issue. Note that at this time details does not support localization.

If the uri specified by license-uri is not a valid Creative Commons license, the web service will reject the request and return an error block. For example,

<error>
  <id>invalid</id>
  <message>Invalid license uri.</message>
</error>

If your application requires more information about a license, the full RDF is available by appending /rdf to the end of any valid Creative Commons License URI. e.g. http://creativecommons.org/licenses/by/3.0/us/rdf

/simple/chooser

Returns a simple license chooser in the form of an HTML-drop down. The format of the returned chooser can be customized with the following parameters

Name Number Description
jurisdiction 0 or 1 Returns licenses for the specified jurisdiction. Example: de
exclude 0 or more Excludes license urls containing the specified string. Example: nc will exclude NonCommercial licenses.
locale 0 or 1 Locale to use for license names; defaults to English (en). Example: ja
select 0 or 1 If specified, the value used for the name attribute of the <select> element; if not specified, the select element is omitted.

If an unknown or unsupported locale is specified, the service will fall back to English. If an unknown jurisdiction is specified, the service will fall back to the Generic jurisdiction.

In addition to these parameters, the Simple Chooser can be further customized by invoking as either /simple/chooser or /simple/chooser.js. If invoked as the former, the result is raw HTML. If invoked as the latter, the result is wrapped in document.write() calls.

/support/jurisdictions

Returns a simple jurisdiction chooser in the form of an HTML drop-down. The format of the returned chooser can be customized with the following parameters

Name Number Description
locale 0 or 1 Locale to use for license names; defaults to English (en). Example: ja
select 0 or 1 If specified, the value used for the name attribute of the <select> element; if not specified, the select element is omitted.

In addition to these parameters, the dropdown call can be further customized by invoking as either /support/jurisdictions or /support/jurisdictions.js. If invoked as the former, the result is raw HTML. If invoked as the latter, the result is wrapped in document.write() calls.

Error Handling

Errors occuring from either invalid input or server-side problems are returned as an XML block, with an <error> top level element. For example, a call to details with no license-uri would return the following text:

<error>
  <id>missingparam</id>
  <message>A value for license-uri must be supplied.</message>
</error>

Error messages are currently not localized.

If the error occurs due to a server side error, two additional elements may be specified: <exception> and <traceback>. <traceback> will contain the text of the Python stack trace. This is usually uninteresting for end users, but may help developers when reporting errors.

<exception> contains the Python exception information. A contrived example:

<exception type="KeyError">
  Unknown Key.
</exception>

Note that the actual contents of the <exception> element is dependent on the actual error that occurs; these will only be returned when an otherwise unhandled error has occured.

Currently Defined Errors

id description
missingparam A required parameter is missing; for convenience the web service will check both GET and POST for form values.
invalidclass Returned when details are requested for an invalid license class. For example, calling /license/blarf will return this error code.
pythonerr A Python exception has occured.
invalidanswer Returned when a value passed into issue or get for a field (question) is not a valid value.

Additional Resources

Table Of Contents

Previous topic

Development Version Documentation

This Page

Navigation

© Copyright 2009, Nathan R. Yergler, Creative Commons. Created using Sphinx 1.0.4.