Development Version Documentation — CC API v documentation
index
previous
CC API v documentation
Development Version Documentation
Author:
Nathan R. Yergler, John E. Doig III
Version:
Development
Updated:
Date: 2011-01-11 13:45:00 -0700 (Tue, 11 Jan 2010)
Document Index
Development Version Documentation
Changes Since 1.5
Access Method
Valid Calls
/locales
/[?locale=xx]
/license/
/license/
Providing work information
Additional work-info details
License return format
/license/
/details?license-uri=[uri]
/simple/chooser
/support/jurisdictions
Error Handling
Currently Defined Errors
Additional Resources
This document covers the current development 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
Changes Since 1.5
Added the
zero
license class and aliased the
publicdomain
class to issue a CC0 result.
Added the
mark
license class (Public Domain Mark).
Refinement of Work Information parameters
/rest/dev/details
Added validation for the specified license URI; returns error
block if invalid
/simple/chooser
The
language
parameter is no longer supported; use
locale
instead.
/support/jurisdictions
The
language
parameter is no longer supported; use
locale
instead.
/license/[class]/
License questions for a class may now include
enumeration items.
Access Method
The Creative Commons Web Services are accessible via a REST interface.
The interface is rooted at
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
...
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),
publicdomain, and recombo (the Sampling licenses).
Classes may be added at any time in the future without
breaking 1.0 compatibility.
A partial example of the returned document is:
If a value for locale is supplied, the service will attempt to return
localized class descriptions. If not specified, English will
be returned.
Note
With the release of the
Public Domain Mark
, the
Public Domain Dedication and Certification
license has been retired. As a result, the
publicdomain
license class has been aliased to the
zero
license class so that the deprecated
Public Domain Dedication and Certification
license is never issued and the
CC0 Public Domain Dedication
license is issued instead. You can read more about Creative Commons’ retired licenses here
/license/
Called with a license class id from the call above as
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
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/
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/
call. A sample answers string for the
previous example is:
This example would issue a by-nc license in the generic (default)
jurisdiction.
The
block is structured using the following
rules:
The
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
tag is the license class prepended
with
license-
Each sub-element of
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
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:
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
, and
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:
This work is licensed under a Creative Commons Attribution 3.0 United States License.
Note the
element contains the HTML as generated by the
CC License Chooser
including machine readable RDFa.
/license/
Called with an HTTP GET and a query string containing a parameter for each
field
specified in the previous call to
/license/
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
apply to
the parameters on the querystring.
The XML returned from this call is identical to the return from
/license/
/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,
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.
/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
language
0 or 1
DEPRECATED
This parameter is deprecated
in favor of locale for consistency.
Language 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