Open Reader API

FeedSink API

by Avi Flax avif@arc90.com of Arc90

This document is copyright © 2013 Arc90, Inc. — but APIs themselves are not subject to copyright, so feel free to implement or reuse the actual API design for any purpose.

This document is licensed to anyone to do anything with. No rights reserved.

Authentication

TBD

Use Cases

As a client, I was just launched, so I want to retrieve all the changes the user made since the last time I checked

Request

Success Response

The response entity will be a JSON object which looks like this:

{
    "feeds": {
        "added": [
            {
                uri: "http://aviflax.com/feed",
                name: "Avi’s Rad Blog",
                "tags": ["racing" "friends"]
            },
            {
                uri: "http://aviflax.com/feed",
                name: "Avi’s Rad Blog",
                "tags": ["racing" "friends"]
            }
        ],
        "deleted": [
            "http//feed.zombo.com/"
        ],
        "updated": [
            {
                uri: "http://aviflax.com/feed",
                name: "Avi’s Rad Blog",
                "tags": ["racing" "friends"]
            },
            {
                uri: "http://aviflax.com/feed",
                name: "Avi’s Rad Blog",
                "tags": ["racing" "friends"]
            }
        ]
    },
    "feed-entries": {
        "http://aviflax.com/feed": {
            "read": [
                'urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a',
                'urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a'
            ],
            "unread": [
                'urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a',
                'urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a'
            ],
            "starred": [
                'urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a',
                'urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a'
            ],
            "unstarred": [
                'urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a',
                'urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a'
            ]
        },
        "http://arc90.com/blog/entries?format=atom": {
            "read": [
                'urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a',
                'urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a'
            ],
            "unread": [
                'urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a',
                'urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a'
            ],
            "starred": [
                'urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a',
                'urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a'
            ],
            "unstarred": [
                'urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a',
                'urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a'
            ]
        }
    }
}

Error Responses

TBD

As a client, I just downloaded new entries from one of a user’s feeds, and I want to check whether any of them have been read already, so that I don’t show the user entries they already read

Request

Success Response

The response entity will be a JSON object which looks like this:

{
    "read_entries": [
        'urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a',
        'urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a',
        'urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a'
    ]
}

Error Responses

TBD

Set the read/unread/starred/unstarred status for entries from one of a user’s feeds

Request

The request entity should be a JSON object which looks like this:

{
    "read": [
        // tuples of entry_id and user_action_date
        [
            'urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a',
            '2013-03-12T23:22:11-04:00'
        ],
        [
            'urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a',
            '2013-03-12T23:22:11-04:00'
        ]
    ],  
    "unread": [
        // tuples of entry_id and user_action_date
        [
            'urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a',
            '2013-03-12T23:22:11-04:00'
        ],
        [
            'urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a',
            '2013-03-12T23:22:11-04:00'
        ]
    ],
    "starred": [
        // tuples of entry_id and user_action_date
        [
            'urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a',
            '2013-03-12T23:22:11-04:00'
        ],
        [
            'urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a',
            '2013-03-12T23:22:11-04:00'
        ]
    ],
    "unstarred": [
        // tuples of entry_id and user_action_date
        [
            'urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a',
            '2013-03-12T23:22:11-04:00'
        ],
        [
            'urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a',
            '2013-03-12T23:22:11-04:00'
        ]
    ],
}

Success Response

Error Responses

TBD

Retrieve the list of all of a user’s feeds

Request

Success Response

The response header Content-Type will be application/json; schema=feedsink.feed-list.v1.0

The response entity will be a JSON object which looks like this:

{
    "feeds": [
        {
            "uri": "http://aviflax.com/feed",
            "name": "Avi’s Silly Blog",
            "tags": ["favorites"],
            "read_entries": [
                'urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a',
                'urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a',
                'urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a'
            ]
        },
        {
            "uri": "http://arc90.com/feed",
            "name": "Arc90 Blog",
            "tags": ["river", "arc"],
            "read_entries": [
                'urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a',
                'urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a',
                'urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a'
            ]
        }
    ]
}

Error Responses

TBD

Add a feed to a user’s list of feeds

Request

The request entity should be a JSON object which looks like this:

{
    "uri": "http://aviflax.com/feed",
    "name": "Avi’s Silly Blog",
    "tags": ["river", "arc/staff"],
}

Please note that a tag may contain / to denote that it is heirarchical.

Success Response

Error Responses

Remove a feed from a user’s list of feeds

Request

Success Response

Error Responses

TBD

Add multiple feeds to a user’s list of feeds

Request

The request entity should be a JSON object which looks like this:

{
    "feeds": [
        {
            "uri": "http://aviflax.com/feed",
            "name": "Avi’s Silly Blog",
            "tags": ["favorites"]
        },
        {
            "uri": "http://arc90.com/feed",
            "name": "Arc90 Blog",
            "tags": ["river", "arc"]
        }
    ]
}

Success Response

Error Responses

Change the name or tags of a user’s feed

Request

The request entity should be a JSON object which looks like this:

{
    "uri": "http://aviflax.com/feed",
    "name": "Avi’s Silly Blog",
    "tags": ["river", "arc/staff"],
}

Success Response

Error Responses

TBD