Skip to content

Restful API for Apps or any other external access

Jump to bottom Edit New page
SSilence edited this page Apr 7, 2013 · 6 revisions

selfoss offers an restful JSON API for applications. If you are a programmer of a mobile app, plugin or any other system which wants to access selfoss then this is your place.

Table of content

# Basics

You can access selfoss by using the same backend as selfoss user interface: The restful HTTP JSON API. There are a few urls where you can get information from selfoss and some for updating data. Assume you want all tags for rendering this in your own app. You have to make an HTTP GET call on the url /tags:

GET http://yourselfossurl.com/tags

The result is following JSON formatted response (in this example two tags "blog" and "deviantart" are available:

[{"tag":"blog","color":"#251f10","unread":"1"},
 {"tag":"deviantart","color":"#e78e5c","unread":"0"}]

Following docs shows you which calls are possible and which response you can expect.

# Errors

If any error occures an HTTP 400 Bad Request Response will returned. The body contains the error message.

# Authentication

When you are using a login protected page, you have to add the parameter username and password in every request (as GET or POST parameter). The logical consequence is that you have to use https.

For an initial login functionality in your app you can validate a username password combination:

GET http://yourselfossurl.com/login

Parameter

  • username the username which should be validated
  • password the password which should be validated

Response

{"success":true}
  • success true = correct login, false = wrong login data
# Items/Articles: List items 
GET http://yourselfossurl.com/items

Parameter

  • type optional set nothing for getting the newest entries, "unread" for getting only unread items and "starred" for getting only marked items.
  • search optional shows only items with given search in title, content or sources title
  • tag optional shows only items of sources with the given tag
  • source optional shows only items of a given source (id of the source)
  • offset optional start listing with given n-th item (for pagination)
  • items optional amount of items which should be returned (for pagination), maximum 200 items per request

Response

Returns a list/array of all items which was found.

[
 {"id":"74",
  "datetime":"2013-04-07 13:43:00",
  "title":"FTTH: Google Fiber f\u00fcr eine neue Gro\u00dfstadt",
  "content":"\n<p>Das 1-GBit\/s-Angebot Google Fiber kommt nach Austin, die Hauptstadt des US-Bundesstaates Texas...",
  "unread":"1",
  "starred":"0",
  "source":"5",
  "thumbnail":"",
  "icon":"0bb93b95508c0b05cd01247dd4f64cdb.png",
  "uid":"http:\/\/www.golem.de\/1304\/98564-rss.html",
  "link":"http:\/\/rss.feedsportal.com\/c\/33374\/f\/578068\/p\/1\/s\/5eab1e78\/l\/0L0Sgol...",
  "sourcetitle":"golem",
  "tags":""},
 ...
]

Every item has following parameters:

  • id the selfoss identifier for this article. Use this for marking or star the entrie later
  • datetime the date and time of the article
  • title the title of the article
  • content the full content of the article
  • unread has value 1 when the article is marked as unread, 0 when the article is marked as read
  • starred has value 1 when the article is marked as starred, 0 when the article is not marked as starred
  • source the id of the source
  • thumbnail the filename of the thumbnail if one was fetched by selfoss
  • icon the filename of the favicon if one was fetched by selfoss
  • uid the uid given by the feed
  • link the link which was given by the rss feed
  • sourcetitle the title of the source (which was entered by the user)
  • tags all tags of the source of this article
# Items/Articles: Mark item as read 
POST http://yourselfossurl.com/mark/@item

Parameter

  • item the id of the item/article

Response

{"success":true}
# Items/Articles: Mark item as unread 
POST http://yourselfossurl.com/unmark/@item

Parameter

  • item the id of the item/article

Response

{"success":true}
# Items/Articles: Mark a list of items as read 
POST http://yourselfossurl.com/mark/

Parameter

  • ids[] a list of all ids for marking as read. e.g. ids%5B%5D=74&ids%5B%5D=16&ids%5B%5D=17&ids%5B%5D=18&ids%5B%5D=19&ids%5B%5D=20&...

Response

{"success":true}
# Items/Articles: Mark item as starred 
POST http://yourselfossurl.com/starr/@item

Parameter

  • item the id of the item/article

Response

{"success":true}
# Items/Articles: Mark item as not starred 
POST http://yourselfossurl.com/unstarr/@item

Parameter

  • item the id of the item/article

Response

{"success":true}
# Items/Articles: Statistics

Returns basic statistic: number of unread items, number of all items, number of starred items.

GET http://yourselfossurl.com/stats

Parameter

none

Response

{"all":"113","unread":"62","starred":"1"}
# Sources: List sources

Returns a list/array of all sources which was found ordered by title.

GET http://yourselfossurl.com/sources/list

Parameter

none

Response

[{
    "id":"2",
    "title":"devart",
    "tags":"da",
    "spout":"spouts\\deviantart\\dailydeviations",
    "params":[],
    "error":"",
    "icon":"8f05d7bb1e00caeb7a279037f129e1eb.png"
 },{
    "id":"1",
    "title":"Tobis Blog",
    "tags":"blog",
    "spout":"spouts\\rss\\feed",
    "params":{
        "url":"http:\/\/blog.aditu.de\/feed"
    },
    "error":"",
    "icon":"7fe3d2c0fc27994dd267b3961d64226e.png"
 },
 ...
]

Every item has following parameters:

  • id the selfoss identifier for this source. Use this for deleting or updating the source.
  • title user given title
  • tags user given tags
  • spout the spout type. You can also get all available spout types by using the json api.
  • params the params the user has set. This depends on the selected spout type. The example shows two different spout types. One without and one with an url parameter.
  • error the error message of the last fetch (empty if no error occured)
  • icon the filename of the favicon if one was found
# Sources: Add or update source 
POST http://yourselfossurl.com/source/@id
POST http://yourselfossurl.com/source

Parameter

  • id the id of a source if you update a given source. Use the second line for adding a new source.
  • title a title for the source
  • spout the spout type for this source. You can get all available spout type by using the json API
  • tags tags for this source
  • parameters of the spout depending on the chosen spout additional parameters are necessary or possible

Response

{"success":true,"id":"8"}
  • id the selfoss identifier for the (new generated or existing) source.
# Sources: Delete source 
DELETE http://yourselfossurl.com/source/@id

Parameter

  • id the id of a source

Response

{"success":true}
# Sources: Get available spouts

Returns all available spouts (types of sources). Every spout has it own parameters.

GET http://yourselfossurl.com/sources/spouts

Parameter

none

Response

{
    "spouts\\deviantart\\dailydeviations": {
        "name":"deviantArt daily deviations",
        "description":"daily deviations of deviantart",
        "params":false
    },
    "spouts\\deviantart\\user": {
        "name":"deviantArt User",
        "description":"deviations of a deviantart user",
        "params":{
            "username": {
                "title":"Username",
                "type":"text",
                "default":"",
                "required":true,
                "validation":["notempty"]
            }
        }
    },
    "spouts\\rss\\feed": {
        "name":"RSS Feed",
        "description":"An default RSS Feed as source",
        "params":{
            "url": {
                "title":"URL",
                "type":"text",
                "default":"",
                "required":true,
                "validation":["notempty"]
            }
        }
    },...
}

Every entry has following parameters:

  • name the name of the spout (show this in spout type selection)
  • description additional description (e.g. for tooltipp)
  • params a list of all parameters with: the parameter title, the type (text, or checkbox or selection), default value, whether its required and a hint for the validation
# Sources: Get unread items per source 
GET http://yourselfossurl.com/sources/stats

Parameter

none

Response

[
 {"id":"2","title":"devart","unread":"12"},
 {"id":"5","title":"golem","unread":"24"},
 {"id":"4","title":"heise","unread":"25"},
 ...
]

Every entry has following parameters:

  • id the id of the source
  • title the title of the source
  • unread the number of unread items of this source
# Tags: List all tags 
GET http://yourselfossurl.com/tags

Parameter

none

Response

[
 {"tag":"blog","color":"#ffc702","unread":"1"},
 {"tag":"da","color":"#e78e5c","unread":"12"},
 ...
]

Every entry has following parameters:

  • tag the tag
  • color the color of this tag
  • unread the number of unread items of this tag
# Tags: Set color of tag 
POST http://yourselfossurl.com/tags/color

Parameter

  • tag the tag
  • color the new color of this tag

Response

{"success":true}
Add a custom footer
Add a custom sidebar
Clone this wiki locally