API/LensAPIs

Connexions Lenses APIs

Connexions lenses are published and returned via Atom and AtomPub. This documentation gives the URL's for retrieving lenses and the contents of lenses and for adding entries to lenses via AtomPub POST.

Lens Code Documentation

URL's for Retrieving Lens Contents

Listing the lenses that a particular account owns

  • http:/cnx.org/lenses/<account id>/atom

Note that, even if the listing is obtained with credentials, only the public lenses will be returned at this time.

Example feed return for account "cnxorg". The individual lenses are returned in the entry links.

<?xml version="1.0" encoding="utf-8"?> 
<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:rhaptos="https://trac.rhaptos.org/trac/rhaptos/wiki/LensAPI"> 
 
    <!-- <feed spoof comment - move above feed to get browser to show xml  --> 
        <author>Connexions</author> 
        <title>Lenses By Connexions</title> 
        <updated>2007-08-13 17:25:32</updated> 
        <id>self.getId()</id> 
        
            <entry> 
                <author>Connexions</author> 
                <title type="text">Connexions Documentation</title> 
                <category term="Affiliation"/> 
                <id>documentation</id> 
                <updated>2011-07-26 11:04:58</updated> 
                <content type="application/xhtml+xml" xml:lang="en"> 
                  <div xmlns="http://www.w3.org/1999/xhtml" class="article"> 
                    <span> 
                      <img src="http://cnx.org/lenses/cnxorg/documentation/logo_thumb"/> 
                    </span> 
                    <ul> 
                      <li> 
                        <strong>Lens by:</strong> 
                        Connexions
                      </li> 
                      <li> 
                        <strong>Content:</strong> 
                        16
                        modules and/or collections
                      </li> 
                      <li> 
                        <a href="http://cnx.org/lenses/cnxorg/documentation/atom">Subscribe to this lens</a> 
                      </li> 
                    </ul> 
                  </div> 
                </content> 
                <link href="http://cnx.org/lenses/cnxorg/documentation"
                      rel="alternate"/> 
            </entry> 
     
            <entry> 
                <author>Connexions</author> 
                <title type="text">Connexions Featured Content</title> 
                <category term="Affiliation"/> 
                <id>featured</id> 
                <updated>2011-11-30 11:04:07</updated> 
                <content type="application/xhtml+xml" xml:lang="en"> 
                  <div xmlns="http://www.w3.org/1999/xhtml" class="article"> 
                    <span> 
                      <img src="http://cnx.org/lenses/cnxorg/featured/logo_thumb"/> 
                    </span> 
                    <ul> 
                      <li> 
                        <strong>Lens by:</strong> 
                        Connexions
                      </li> 
                      <li> 
                        <strong>Content:</strong> 
                        33
                        modules and/or collections
                      </li> 
                      <li> 
                        <a href="http://cnx.org/lenses/cnxorg/featured/atom">Subscribe to this lens</a> 
                      </li> 
                    </ul> 
                  </div> 
                </content> 
                <link href="http://cnx.org/lenses/cnxorg/featured"
                      rel="alternate"/> 
            </entry> 
</feed> 

Using AtomPub to add Modules and Collections to Lenses

Note that currently only POST is allowed and the Location returned is of the lens that was POSTed to, rather than the entry that was just added.

Adding a module to a lens

When adding modules to lenses, the lensmaker can add

  • tags relevant to the module. Tags could be from custom vocabularies or content standards.
  • comment that adds information relevant to the lenses audience. Comments could be reviews, usage comments, or any other information.
  • Version range: versionStart and versionStop. The lens entry may also specify which versions of the module are to be included in the lens, including specifying that all future versions should be included.

Example curl request:

curl -s --request POST --header "Content-Type: application/atom+xml;type=entry" --user cnxorg:nottherealpassword --upload-file atom-add-module-to-lens.xml http://testsword.rhaptos.org:8080/lenses/cnxorg/featured/atompub

Example request adding module 10005 to cnxorg's lens "Featured Content":

POST http://cnx.org/lenses/cnxorg/featured/atompub HTTP/1.1
Host: cnx.org
Authorization: Basic ZGFmZnk6c2VjZXJldA==
Content-Length: [content length]
Content-Type: multipart/related;
            boundary="===============1605871705==";
            type="application/atom+xml"
In-Progress: true
MIME-Version: 1.0

Media Post
--===============1605871705==
Content-Type: application/atom+xml; charset="utf-8"
Content-Disposition: attachment; name="atom"
MIME-Version: 1.0

[Atom Entry]

Example [Atom Entry] for module m10005:

<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:dcterms="http://purl.org/dc/terms/"
       xmlns:rhaptos="https://trac.rhaptos.org/trac/rhaptos/wiki/LensAPI"> 

    <id>m10005</id> 
    <rhaptos:comment>Used as supplemental materials for developmental math courses.</rhaptos:comment> <!-- These don't allow any html right now -->
    <rhaptos:tag>foo</rhaptos:tag>
    <rhaptos:tag>bar</rhaptos:tag>
    <rhaptos:versionStart>1.1</rhaptos:versionStart> <!-- start version, leave empty for beginning -->
    <rhaptos:versionStop></rhaptos:versionStop> <!-- stop version, leave empty for all to latest <-->
</entry>

Adding a collection to a lens

In addition to the same parameters that can be set for modules, for Collections.

  • inclusive property: <rhaptos:inclusive>True</rhaptos:inclusive> <!-- If true, show this lens on modules that are inside this collection, even when they are viewed from outside the collection, such as from a web search. The default is "true". -->

Example atom entry for col10001:

<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:dcterms="http://purl.org/dc/terms/"
       xmlns:rhaptos="https://trac.rhaptos.org/trac/rhaptos/wiki/LensAPI"> 

    <id>col10001</id> 
    <rhaptos:comment>Used as supplemental materials for developmental math courses.</rhaptos:comment> <!-- These don't allow any html right now -->
    <rhaptos:tag>math</rhaptos:tag>
    <rhaptos:tag>science</rhaptos:tag>
    <rhaptos:inclusive>True</rhaptos:inclusive> <!-- Only applicable to collections, If true, show this lens on modules that are inside this collection, even when they are viewed from outside the collection, such as from a web search. -->
    <rhaptos:versionStart>1.1</rhaptos:versionStart> <!-- start version, leave empty for beginning -->
    <rhaptos:versionStop></rhaptos:versionStop> <!-- stop version, leave empty for all to latest <-->
</entry>

Errors

Adding a module or collection that is already in the lens

If you attempt to add a module or collection to a lens that already contains that module, you will get an HTTP 403 error and a message that indicates that the module <moduleid> is already in the lens <lensid>. The lensid is the last part of the URL for the lens.

Example error Header:

HTTP/1.1 403 Forbidden
Server: Zope/(Zope 2.9.10-final, python 2.4.6, linux2) ZServer/1.1 Plone/2.5.5
Date: Mon, 16 Jan 2012 18:39:28 GMT
Content-Length: 54
Content-Type: text/html; charset=utf-8
Set-Cookie: I18N_LANGUAGE="en"; Path=/

Example Error Output:

Module m10005 is already part of the lens rochelens