diretto Feed APIv2 - Draft

diretto Feed API

Introduction

Version

v2 - Draft

Author

Benjamin Erb

Description

The Feed API provides non-JSON lists of entries in popular feed formats. It can be used for retrieving lists of available documents and attachments. Some of the feeds are PubSubHubbub-enabled, which allows clients to register for notifications upon new items. See also the Streaming API and the list resources of the Core API as alternatives.

Authentication Schemes

Basic Authentication

Base URI

http://feed.example.foo/v2

1. Atom Feeds

Description

The following sub-resources provide feeds of entries added to the platform as Atom feeds. Feeds are paginated as described in RFC 5005.

Resource URI

http://feed.example.foo/v2/feed

1.1 Document details feed

Description

An Atom feed of items related to the given document. This feed will include comments and attachments.

URI

http://feed.example.foo/v2/feed/document/{doc-id}

URI Parameters

{doc-id}: document id'

HTTP Method

GET

Resource Formats

application/atom+xml

Authentication

not required

Request Entities

n/a

Responses

200 OK: Feed in response

Response Entities

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
	<generator uri="http://www.diretto.org" version="0.1.0">diretto Feed Node</generator>
	<link rel="self" href="http://feed.example.foo/v2/feeds/document/eafbad70-7972-11e0-a1f0-0800200c9a66" />
	<link rel="alternate" href="http://core.example.foo/v2/document/eafbad70-7972-11e0-a1f0-0800200c9a66" />
	<link rel="hub" href="http://hub.example.foo/" />
	<title>Document details feed</title>
	<id>http://feed.example.foo/v2/feeds/document/eafbad70-7972-11e0-a1f0-0800200c9a66</id>
	<updated>2010-07-17T18:54:11.939Z</updated>
	
	 <entry>
		<id>http://core.example.foo/v2/document/eafbad70-7972-11e0-a1f0-0800200c9a66/comment/8e252710-77cf-11e0-a1f0-0800200c9a66</id>
		<title>Comment 8e252710-77cf-11e0-a1f0-0800200c9a66</title>
		<updated>2010-07-17T18:54:11.939Z</updated>
		<category term="comment" />
		<author>
			<uri>http://core.example.foo/v2/user/123456</uri>
		</author>
		<content>blablabla</content>
	 </entry>    	
	
	 <entry>
		<id>http://core.example.foo/v2/document/eafbad70-7972-11e0-a1f0-0800200c9a66/attachment/eafbad70-7972-11e0-a1f0-0800200c9a66</id>
		<title>A cool image of Foobar</title>
		<updated>2010-07-17T18:54:11.939Z</updated>
		<category term="image" />
		<author>
			<uri>http://core.example.foo/v2/user/123456</uri>
		</author>
		<link rel="enclosure" href="http://storage.example.foo/eafbad70-7972-11e0-a1f0-0800200c9a66/attachment/eafbad70-7972-11e0-a1f0-0800200c9a66.jpg" length="61312" type="image/jpeg" />
	 </entry>    
	 	 
	 <!-- more entries -->
 
</feed>

1.2 List of attachments

Description

An Atom feed of attachments added to the platform, sorted by creation time. Note that this feed will contain items referring to different documents. This feed is PubSubHubbub-enabled.

URI

http://feed.example.foo/v2/feed/attachments

URI Parameters

n/a

HTTP Method

GET

Resource Formats

application/atom+xml

Authentication

not required

Request Entities

n/a

Responses

200 OK: Feed in response

Response Entities

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
	<generator uri="http://www.diretto.org" version="0.1.0">diretto Feed Node</generator>
	<link rel="self" href="http://feed.example.foo/v2/feed/attachments/cursor/d3419a0c-bc9a-493f-b842-e43bf1bc5e10" />
	<link rel="alternate" href="http://www.example.foo" />
	<link rel="next" href="http://feed.example.foo/v2/feed/attachments/cursor/86a4d8de-b358-43ff-a465-7d32a137c63c" />
	<link rel="previous" href="http://feed.example.foo/v2/feed/attachments/cursor/03f2fc31-412b-4dc6-9973-87bb03c286f7" />
	<link rel="hub" href="http://hub.example.foo/" />
	<title>List of Attachments</title>
	<id>http://feed.example.foo/v2/feed/attachments</id>
	<updated>2010-07-17T18:54:11.939Z</updated>
	
	 <entry>
		<id>http://core.example.foo/v2/document/eafbad70-7972-11e0-a1f0-0800200c9a66/attachment/eafbad70-7972-11e0-a1f0-0800200c9a66</id>
		<title>A cool image of Foobar</title>
		<updated>2010-07-17T18:54:11.939Z</updated>
		<category term="image" />
		<author>
			<uri>http://core.example.foo/v2/user/123456</uri>
		</author>
		<link rel="enclosure" href="http://storage.example.foo/eafbad70-7972-11e0-a1f0-0800200c9a66/attachment/eafbad70-7972-11e0-a1f0-0800200c9a66.jpg" length="61312" type="image/jpeg" />
	 </entry>    
	 
	 <!-- more entries -->
 
</feed>

1.3 List of comments

Description

An Atom feed of comments added to the platform, sorted by creation time. Note that this feed will contain items referring to different documents. This feed is PubSubHubbub-enabled.

URI

http://feed.example.foo/v2/feed/comments

URI Parameters

n/a

HTTP Method

GET

Resource Formats

application/atom+xml

Authentication

not required

Request Entities

n/a

Responses

200 OK: Feed in response

Response Entities

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
	<generator uri="http://www.diretto.org" version="0.1.0">diretto Feed Node</generator>
	<link rel="self" href="http://feed.example.foo/v2/feed/comments/cursor/d3419a0c-bc9a-493f-b842-e43bf1bc5e10" />
	<link rel="alternate" href="http://www.example.foo" />
	<link rel="next" href="http://feed.example.foo/v2/feed/comments/cursor/86a4d8de-b358-43ff-a465-7d32a137c63c" />
	<link rel="previous" href="http://feed.example.foo/v2/feed/comments/cursor/03f2fc31-412b-4dc6-9973-87bb03c286f7" />
	<link rel="hub" href="http://hub.example.foo/" />
	<title>List of Attachments</title>
	<id>http://feed.example.foo/v2/feed/comments</id>
	<updated>2010-07-17T18:54:11.939Z</updated>
	
	 <entry>
		<id>http://core.example.foo/v2/document/eafbad70-7972-11e0-a1f0-0800200c9a66/comment/8e252710-77cf-11e0-a1f0-0800200c9a66</id>
		<title>Comment 8e252710-77cf-11e0-a1f0-0800200c9a66</title>
		<updated>2010-07-17T18:54:11.939Z</updated>
		<category term="comment" />
		<author>
			<uri>http://core.example.foo/v2/user/123456</uri>
		</author>
		<content>blablabla</content>
	 </entry>    
	 
	 <!-- more entries -->
 
</feed>

1.4 List of media-specific documents

Description

An Atom feed of documents filtered by media type and sorted by publish time. The media type is described by the first part of the MIME type. This feed is PubSubHubbub-enabled.

URI

http://feed.example.foo/v2/feed/media/{media-type}

URI Parameters

{media-type}: Media type, i.e. 'image' or 'text'

HTTP Method

GET

Resource Formats

application/atom+xml

Authentication

not required

Request Entities

n/a

Responses

200 OK: Feed in response

Response Entities

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
	<generator uri="http://www.diretto.org" version="0.1.0">diretto Feed Node</generator>
	<link rel="self" href="http://feed.example.foo/v2/feed/media/image/cursor/eafbad70-7972-11e0-a1f0-0800200c9a66" />
	<link rel="alternate" href="http://www.example.foo" />
	<link rel="next" href="http://feed.example.foo/v2/feed/media/image/cursor/86a4d8de-b358-43ff-a465-7d32a137c63c" />
	<link rel="previous" href="http://feed.example.foo/v2/feed/media/image/cursor/03f2fc31-412b-4dc6-9973-87bb03c286f7" />
	<link rel="hub" href="http://hub.example.foo/" />
	<title>List of published documents</title>
	<id>http://feed.example.foo/v2/feed/media/image</id>
	<updated>2010-07-17T18:54:11.939Z</updated>
	
	 <entry>
		<id>http://core.example.foo/v2/document/eafbad70-7972-11e0-a1f0-0800200c9a66</id>
		<title>A cool image of fubar</title>
		<updated>2010-07-17T18:54:11.939Z</updated>
		<category term="document" />
		<author>
			<uri>http://core.example.foo/v2/user/123456</uri>
		</author>
		<summary>blablabla</summary>
		<link rel="enclosure" href="http://storage.example.foo/eafbad70-7972-11e0-a1f0-0800200c9a66/attachment/eafbad70-7972-11e0-a1f0-0800200c9a66.jpg" length="61312" type="image/jpeg" />		
	 </entry>    
	 
	 <!-- more entries -->
 
</feed>

1.5 List of published documents

Description

An Atom feed of documents added to the platform, sorted by publish time. This feed is PubSubHubbub-enabled.

URI

http://feed.example.foo/v2/feed/documents

URI Parameters

n/a

HTTP Method

GET

Resource Formats

application/atom+xml

Authentication

not required

Request Entities

n/a

Responses

200 OK: Feed in response

Response Entities

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
	<generator uri="http://www.diretto.org" version="0.1.0">diretto Feed Node</generator>
	<link rel="self" href="http://feed.example.foo/v2/feed/documents/cursor/eafbad70-7972-11e0-a1f0-0800200c9a66" />
	<link rel="alternate" href="http://www.example.foo" />
	<link rel="next" href="http://feed.example.foo/v2/feed/documents/cursor/86a4d8de-b358-43ff-a465-7d32a137c63c" />
	<link rel="previous" href="http://feed.example.foo/v2/feed/documents/cursor/03f2fc31-412b-4dc6-9973-87bb03c286f7" />
	<link rel="hub" href="http://hub.example.foo/" />
	<title>List of published documents</title>
	<id>http://feed.example.foo/v2/feed/documents</id>
	<updated>2010-07-17T18:54:11.939Z</updated>
	
	 <entry>
		<id>http://core.example.foo/v2/document/eafbad70-7972-11e0-a1f0-0800200c9a66</id>
		<title>A cool image of fubar</title>
		<updated>2010-07-17T18:54:11.939Z</updated>
		<category term="document" />
		<author>
			<uri>http://core.example.foo/v2/user/123456</uri>
		</author>
		<summary>blablabla</summary>
		<link rel="enclosure" href="http://storage.example.foo/eafbad70-7972-11e0-a1f0-0800200c9a66/attachment/eafbad70-7972-11e0-a1f0-0800200c9a66.jpg" length="61312" type="image/jpeg" />		
	 </entry>    
	 
	 <!-- more entries -->
 
</feed>

2. Geo Feeds

Description

The following sub-resources provide feeds of entries added to the platform as spatial KML feeds.

Resource URI

http://feed.example.foo/v2/feed/geo

2.1 List of document positions within a given bounding box

Description

A KML feed of all document positions that are inside the given bounding box. The maximum size of the response is limited. If the number of hits in the requested area exceeds a limit, the request will be denied and should be returned using a smaller bounding box. If a document has multiple suggested positions, the best ranked will be chosen.

URI

http://feed.example.foo/v2/feed/geo/area?bbox={minX},{minY},{maxX},{maxY}

URI Parameters

{minX}: min X value of bounding box
{minY}: min Y value of bounding box
{maxX}: max X value of bounding box
{maxY}: max Y value of bounding box

HTTP Method

GET

Resource Formats

application/vnd.google-earth.kml+xml

Authentication

not required

Request Entities

n/a

Responses

200 OK: Feed in response
400 Bad Request: Invalid bounding box
403 Forbidden: Too much hits, decrease bounding box size and retry

Response Entities

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2" xmlns:atom="http://www.w3.org/2005/Atom">
<Document>
	<name>List of document positions within a given bounding box: {minX},{minY},{maxX},{maxY}</name>


	<!-- styles omitted -->

	<Placemark>
		<name>Document tile</name>
		<description></description>
        <atom:link rel="alternate" href="http://core.example.foo/v2/document/eafbad70-7972-11e0-a1f0-0800200c9a66" />

		<Point>
			<coordinates>10.01,49.7,0</coordinates>
		</Point>
	</Placemark>

	<!-- more entries -->

 </Document>
</kml>

2.2 Positions of the latest documents published

Description

A KML feed containing the positions of the latest document added to the platform. If a document has multiple suggested positions, the best ranked will be chosen.

URI

http://feed.example.foo/v2/feed/geo/documents

URI Parameters

n/a

HTTP Method

GET

Resource Formats

application/vnd.google-earth.kml+xml

Authentication

not required

Request Entities

n/a

Responses

200 OK: Feed in response

Response Entities

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2" xmlns:atom="http://www.w3.org/2005/Atom">
<Document>
	<name>Positions of the latest documents published</name>


	<!-- styles omitted -->

	<Placemark>
		<name>Document tile</name>
		<description>Document Description</description>
		  <atom:author>
			<atom:uri>http://core.example.foo/v2/user/123456</atom:uri>		  	
		  </atom:author>
		  <atom:link rel="alternate" href="http://core.example.foo/v2/document/eafbad70-7972-11e0-a1f0-0800200c9a66" />

		<Point>
			<coordinates>10.01,49.7,0</coordinates>
		</Point>
	</Placemark>

	<!-- more entries -->

 </Document>
</kml>

2.3 Suggested positions for a specific document

Description

A KML feed of the positions that users have suggested as origin for a document.

URI

http://feed.example.foo/v2/feed/geo/document/{doc-id}/positions

URI Parameters

{doc-id}: document id'

HTTP Method

GET

Resource Formats

application/vnd.google-earth.kml+xml

Authentication

not required

Request Entities

n/a

Responses

200 OK: Feed in response

Response Entities

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2" xmlns:atom="http://www.w3.org/2005/Atom">
<Document>
	<name>Suggested positions for document 32b8c320-a28e-11e0-8264-0800200c9a66</name>


	<!-- styles omitted -->

	<Placemark>
		<name>48.39848,9.991246,100</name>
		<description>Position 48.39848,9.991246; Variance: 100m</description>
		  <atom:author>
			<atom:uri>http://core.example.foo/v2/user/123456</atom:uri>		  	
		  </atom:author>
		  <atom:link rel="alternate" href="http://core.example.foo/v2/document/32b8c320-a28e-11e0-8264-0800200c9a66/location/48.39848,9.991246,100" />

		<Point>
			<coordinates>9.991246,48.39848,0</coordinates>
		</Point>
	</Placemark>

	<!-- more entries -->

 </Document>
</kml>

3. Index

Description

This entry resource provides information about the instance.

Resource URI

http://feed.example.foo/v2

3.1 Get service instance data

Description

Returns a static information about the deployed Feed API service instance.

URI

http://feed.example.foo/v2

URI Parameters

n/a

HTTP Method

GET

Resource Formats

application/json

Authentication

not required

Request Entities

n/a

Responses

200 OK: Service instance data in response entity

Response Entities

{
   "api":{
      "name":"org.diretto.api.main.feed",
      "version":"v2"
   },
   "service":{
      "name":"diretto Feed API Node",
      "version":"0.1.0"
   },
   "deployment":{
      "title":"fubar Feed Service",
      "contact":"n/a",
      "website":{
         "link":{
            "rel":"self",
            "href":"http://www.diretto.org"
         }
      }
   },
   "links":[
      {
         "title":"diretto Feed API Documentation",
         "link":{
            "rel":"self",
            "href":"http://diretto.github.com/diretto-api-doc/v2/diretto/feed.html"
         }
      },
      {
         "title":"Atom feed of published documents",
         "link":{
            "rel":"self",
            "href":"http://feed.diretto.org/v2/feed/documents"
         }
      },
      {
         "title":"Atom feed of published comments",
         "link":{
            "rel":"self",
            "href":"http://feed.diretto.org/v2/feed/comments"
         }
      },
      {
         "title":"Atom feed of published attachments",
         "link":{
            "rel":"self",
            "href":"http://feed.diretto.org/v2/feed/attachments"
         }
      },
      {
         "title":"Atom feed of published documents of a distinct media type",
         "link":{
            "rel":"self",
            "href":"http://feed.diretto.org/v2/feed/media/{type}"
         }
      },
      {
         "title":"Atom feed of resources related to a distinct document",
         "link":{
            "rel":"self",
            "href":"http://feed.diretto.org/v2/feed/document/{id}"
         }
      }
   ],
   "parameters":{
      "paginationSize":20
   }
}

The JSON response contains information about the service identification and version, the actual deployment variables and links to the main service instance.