discussion of the Creative Commons Metadata work

[Ben Adida <ben AT mit.edu>]

Nathan,

Very happy to see this development of a SOAP API for CC.

Here are a few comments:

> licenses()
>   Returns a list of license class identifiers (currently standard, 
> publicdomain; gpl, lgpl, recombo will be added)

You should probably rename this license_classes() if you're returning 
classes of licenses, and not licenses themselves. You'll probably want 
to attach a description for each class of license, too, not just a 
class identifier. So this call would return a set of records, each one 
being a complete license class with identifier, description, and maybe 
more if you think there's any reason for more data.

> fields(license)
>   Returns a list of field identifiers for a particular license class; 
> fields are values which must be supplied in order to issue a license
>
> fieldDetail(license, field_id, lang='en')
>   Returns a sequence of two-tuples which form a detail mapping for the 
> particular field.  Keys include id, label, description and type.

I can't think of when one would want to use fields() without 
immediately calling fieldDetail() on every return value. I would 
suggest an approach with slightly more data per call, and fewer calls, 
because these distributed API calls tend to have sizable overhead 
(latency and data quantity). So, maybe just fields(license) returning 
the complete set of field records including details?

> fieldEnum(license, field_id, lang='en')
>   For fields with type=='enum', returns a mapping of id/label pairs

Again, I would recommend packaging this within the fields() call. 
You're not talking about that much data overall.

> getLicense(license, answers)
>   Returns an XML document containing the license URL and license RDF; 
> license is the license class ID and answers is a mapping (dictionary) 
> with field identifiers as the keys.

good, though license() might be more consistent with your previous 
naming scheme.

> The following questions still need to be answered:
>
> * How to handle work information, which should be integrated into the 
> returned license RDF (always add the keys to the field list?  seperate 
> function to get the work info fields and return them in an additional, 
> optional parameter to getLicense?)

I would recommend keeping the work RDF generation API completely 
separate from the license engine API. The work API can take as input a 
license_url field (which could be non-CC over time, btw).

> * Exceptions are currently poorly defined and hence relatively useless

You'll probably get the best feel for those as you develop ccTag.

Looking forward to this!

-Ben