Table of Contents generated with DocToc

About the REST API

Our reader.tidhr.com has also a REST API with support for external 3rd party apps. This document describes this API.

The base URL for our REST service is https://reader.tidhr.com/rest. You can use HTTPS or HTTP.

Our frontend has been built by using this API.


1. Access Tokens

Users can create their own access tokens after log in at https://reader.tidhr.com/authorizations.

Please note: You must save the content in the provided token and secret properties or otherwise that access token is useless. You cannot get the value of secret if you don't save it!


2. Resources

Our API resources are usually JSON objects.

These objects may contain partial child objects from other online resources if the child object has $ref property which points to an another online resource. Exception is if the object itself has $ref as the first level property -- then it is the link to the resource itself.


2.1. Internal Database Schema

We use PostgreSQL 9.3 with new JSON support.

Here is our database schema:

Database Schema

Most of our API objects use same names.

Note: All passwords and access token secrets are hashed with PostgreSQL crypt(). That's why these values cannot be fetched from the API again.


3. Get all available resources from the REST API

Sample output:

{
   "profile" : {
      "$ref" : "http://reader.tidhr.com/rest/profile"
   },
   "feeds" : {
      "$ref" : "http://reader.tidhr.com/rest/feeds"
   },
   "access_token" : {
      "profile" : true,
      "part_feed" : false,
      "edit_profile" : true,
      "import_feed" : true,
      "description" : "Bot",
      "bots" : true,
      "users_id" : null,
      "read_feed" : true,
      "edit_pages" : true,
      "join_feed" : true,
      "debug" : true,
      "token" : "6ef1b3b68a60aa2749e5f1b1c1dbef40",
      "pages" : true
   },
   "auth" : {
      "$ref" : "http://reader.tidhr.com/auth"
   },
   "authorizations" : {
      "$ref" : "http://reader.tidhr.com/rest/authorizations"
   },
   "register" : {
      "$ref" : "http://reader.tidhr.com/rest/register"
   },
   "bots" : {
      "$ref" : "http://reader.tidhr.com/rest/bots"
   },
   "debug" : {
      "$ref" : "http://reader.tidhr.com/rest/debug"
   },
   "pages" : {
      "$ref" : "http://reader.tidhr.com/rest/pages"
   }
}

Possible optional properties for this resource are feeds, debug, bots, profile, authorizations, access_token, register, pages, and auth.

These properties are included only if your access token or authorized session has correct privileges. Some resources are public.


3.1. Pages


3.1.1. Listing pages

Get a list of page objects.

Sample output:

[
   {
      "title" : "About",
      "$ref" : "http://reader.tidhr.com/rest/pages/about"
   },
   {
      "title" : "API",
      "$ref" : "http://reader.tidhr.com/rest/pages/api"
   }
]

3.1.1.1. Get page resource
{
   "content_type" : "text/x-markdown",
   "content" : "About the reader\n======\n\nThis is our NKO entry -- a RSS/Atom reader.",
   "name" : "about",
   "title" : "About",
   "$ref" : "http://reader.tidhr.com/rest/pages/about"
}

3.1.1.2. Updates the page content

Example input body (with Content-Type header as application/json):

{
   "content_type" : "text/x-markdown",
   "content" : "About the reader\n======\n\nThis is our NKO entry -- a RSS/Atom reader.",
   "name" : "about",
   "title" : "About",
}

3.1.1.3. Delete the page resource

3.1.2. Creating a new page

Example input body (with application/json content type):

{
   "content_type" : "text/x-markdown",
   "content" : "About the reader\n======\n\nThis is our NKO entry -- a RSS/Atom reader.",
   "name" : "about",
   "title" : "About",
}

Pages use Markdown syntax by default. (Actual library we are using is marked.)


3.2. Authorizations and Access Tokens


3.2.1. Get list of access tokens

Example output:

[
   {
      "description" : "Test",
      "token" : "f78678efd12d9d9f3d4bc3f91eca3222",
      "$ref" : "https://reader.tidhr.com/rest/authorizations/f78678efd12d9d9f3d4bc3f91eca3222"
   },
   {
      "description" : "Test 2",
      "token" : "2c3a42b8373e872b66d636dc8ed50eb3",
      "$ref" : "https://reader.tidhr.com/rest/authorizations/2c3a42b8373e872b66d636dc8ed50eb3"
   },
   {
      "description" : "Test3",
      "token" : "66dc251d61d46f4d567784757726f0ca",
      "$ref" : "https://reader.tidhr.com/rest/authorizations/66dc251d61d46f4d567784757726f0ca"
   }
]

3.2.1.1. Get access token resource

Example response:

{
   "profile" : false,
   "part_feed" : false,
   "edit_profile" : false,
   "import_feed" : false,
   "description" : "Test",
   "bots" : false,
   "users_id" : 13,
   "read_feed" : true,
   "edit_pages" : false,
   "join_feed" : true,
   "debug" : false,
   "token" : "f78678efd12d9d9f3d4bc3f91eca3222",
   "pages" : false
}

3.2.1.2. Delete access token

3.2.2. Create a new access token

JSON example request body:

{
   "description": "",
   "join_feed": "true",
   "read_feed": "true",
   "part_feed": "true",
   "profile": "true",
   "edit_profile": "false",
}

These properties are all optional and will be the same default values as in the example.

Note: Because of a bug in our code you cannot change edit_profile, and we cannot fix our app code during the Node Knockout competition.

You will get this object as response:

{
   "profile" : true,
   "part_feed" : true,
   "secret" : "gtI0nWrpISr8S2Ma46xMSEP65Xc9irSQ",
   "edit_profile" : false,
   "import_feed" : false,
   "$ref" : "http://reader.tidhr.com/rest/authorizations/554a3adb75c62be589b4620820a40d26",
   "description" : "",
   "bots" : false,
   "users_id" : 123,
   "read_feed" : true,
   "edit_pages" : false,
   "join_feed" : true,
   "debug" : false,
   "token" : "554a3adb75c62be589b4620820a40d26",
   "pages" : false
}

3.3. Returns debug information from the service.

You will get this object as response:

{
   "uid" : 1000,
   "groups" : [
      1000
   ],
   "gid" : 1000
}

3.4. User Profile


3.4.1. Get current profile information

You will get this object as response:

{
   "profile" : {
      "provider" : "github",
      "emails" : [
         {
            "value" : "jheusala@example.com"
         }
      ],
      "id" : 123456,
      "profileUrl" : "https://github.com/jheusala",
      "username" : "jheusala",
      "displayName" : "Jaakko-Heikki Heusala"
   },
   "id" : 123,
   "username" : "jhh"
}

3.4.2. Update user profile

Example input body:

{
   "username": "jhh",
   "password": "abcdefgh12345"
}

3.5. Registration


3.5.1. Registration

Example request body:

{
   "username": "john",
   "password": "1234567"
}

3.5.2. Registration (with GET)

This resource actually does nothing and is only provided as a customary manner.

You will get this object as response:

{}

3.6. Bots


3.6.1. Get list of active bots

You will get this object as response:

[
   {
      "last_active" : "2013-11-11T08:03:58.087Z",
      "id" : 6,
      "$ref" : "http://reader.tidhr.com/rest/bots/6"
   },
   {
      "last_active" : "2013-11-11T08:04:00.735Z",
      "id" : 7,
      "$ref" : "http://reader.tidhr.com/rest/bots/7"
   },
   {
      "last_active" : "2013-11-11T08:04:01.941Z",
      "id" : 8,
      "$ref" : "http://reader.tidhr.com/rest/bots/8"
   },
   {
      "last_active" : "2013-11-11T08:04:02.472Z",
      "id" : 9,
      "$ref" : "http://reader.tidhr.com/rest/bots/9"
   },
   {
      "last_active" : "2013-11-11T08:04:03.537Z",
      "id" : 10,
      "$ref" : "http://reader.tidhr.com/rest/bots/10"
   },
   {
      "last_active" : "2013-11-11T08:04:11.747Z",
      "id" : 11,
      "$ref" : "http://reader.tidhr.com/rest/bots/11"
   }
]

3.6.2. When a bot wants to register on the server and get an ID

You will get this object as response:

```

******************************************************************************


#### 3.6.3. When a bot wants to unregister from the server

* `DELETE /rest/bots/:bot_id`
* Requires `bots` privilege.

You will get this object as response:

```json

3.6.4. Get bots own resource

You will get this object as response:

{
   "feeds" : {
      "$ref" : "http://reader.tidhr.com/rest/bots/11/feeds"
   }
}

3.6.5.1. Get feeds for specific bot

You will get this object as response:

[
   {
      "fetchtime" : "2013-11-11T13:48:51.704Z",
      "$ref" : 
"http://reader.tidhr.com/rest/feeds/c5108ac84f5098aad2b35e3e4f398f92a0154d98"
   }
]

3.7. Feeds


3.7.1. Get all feeds available for this session

You will get this object as response:

[
   {
      "title" : "Uutiset - HS.fi",
      "$ref" : "http://reader.tidhr.com/rest/feeds/8b60e02efd93face9edd246f6763bf5a0cf5211a"
   },
   {
      "title" : "Yle Uutiset | Oulu | Tuoreimmat uutiset",
      "$ref" : "http://reader.tidhr.com/rest/feeds/884b15d1eb470eea8b8115298fbc89c2e02db197"
   },
   {
      "title" : "EPisodeWorld RSS feed: All Shows",
      "$ref" : "http://reader.tidhr.com/rest/feeds/5db57a6dfd42b9cc99c0912e9308b8a0847ce459"
   },
   {
      "title" : "RT - Daily news",
      "$ref" : "http://reader.tidhr.com/rest/feeds/f727d4e7e321e0dfe50c1ce0b866147b453f069d"
   }
]

3.7.2. Subscribe to a new feed

Example request body:

{
   "feedurl": "http://rss.cnn.com/rss/edition.rss"
}

3.7.3 Unsubscribe from specific feed


3.7.4. Get specific feed object

You will get this object as response:

{
   "id" : "884b15d1eb470eea8b8115298fbc89c2e02db197",
   "feedurl" : "http://yle.fi/uutiset/rss/uutiset.rss?osasto=oulu",
   "title" : "Yle Uutiset | Oulu | Tuoreimmat uutiset",
   "$ref" : "http://reader.tidhr.com/rest/feeds/884b15d1eb470eea8b8115298fbc89c2e02db197",
   "meta" : {
      "pubdate" : null,
      "date" : null,
      "rss:category" : {
         "#" : "Tuoreimmat uutiset",
         "@" : {}
      },
      "copyright" : null,
      "author" : null,
      "generator" : null,
      "cloud" : {},
      "rss:title" : {
         "#" : "Yle Uutiset | Oulu | Tuoreimmat uutiset",
         "@" : {}
      },
      "rss:@" : {},
      "@" : [
         {
            "xmlns:content" : "http://purl.org/rss/1.0/modules/content/"
         }
      ],
      "link" : "http://yle.fi/uutiset/",
      "#version" : "2.0",
      "rss:link" : {
         "#" : "http://yle.fi/uutiset/",
         "@" : {}
      },
      "#xml" : {
         "version" : "1.0",
         "encoding" : "UTF-8"
      },
      "language" : null,
      "favicon" : null,
      "categories" : [
         "Tuoreimmat uutiset"
      ],
      "description" : "Yle Uutiset | Oulu | Tuoreimmat uutiset",
      "image" : {},
      "rss:description" : {
         "#" : "Yle Uutiset | Oulu | Tuoreimmat uutiset",
         "@" : {}
      },
      "#ns" : [
         {
            "xmlns:content" : "http://purl.org/rss/1.0/modules/content/"
         }
      ],
      "xmlUrl" : null,
      "title" : "Yle Uutiset | Oulu | Tuoreimmat uutiset",
      "#type" : "rss",
      "pubDate" : null,
      "xmlurl" : null
   },
   "items" : {
      "$ref" : "http://reader.tidhr.com/rest/feeds/884b15d1eb470eea8b8115298fbc89c2e02db197/items"
   }
}

3.7.5. Get specific feed items

You will get this object as response:

[
   {
      "summary" : "Nenäpäivän juhlijat valtasivat perjantaina Oulun kävelykatu Rotuaarin. Katso kuvia Nenäpäivän vietosta.",
      "read" : false,
      "title" : "Oulun Rotuaari muuttui punanenäisten kaduksi",
      "$ref" : "http://reader.tidhr.com/rest/feeds/884b15d1eb470eea8b8115298fbc89c2e02db197/items/7cfcce756090b565fdc5b9132b0ea9a6be4f0290"
   },
   {
      "summary" : "Kolea sääkään ei saanut hyväntekijöitä hyytymään. Oulussa järjestetyissä tapahtumissa kerättiin yhteensä 5555 euroa.",
      "read" : false,
      "title" : "Nenäpäivä keräsi Oulussa ennätyssumman",
      "$ref" : "http://reader.tidhr.com/rest/feeds/884b15d1eb470eea8b8115298fbc89c2e02db197/items/99890e9c2beb41e359d635421242e415eb51cad0"
   },
   {
      "summary" : "Alun perin omistajien piti päättää jatkostaan lokakuun loppuun mennessä, mutta heille annettiin viikon verran lisäaikaa.",
      "read" : false,
      "title" : "Fennovoiman omistajien kerrottava jatkostaan tänään",
      "$ref" : "http://reader.tidhr.com/rest/feeds/884b15d1eb470eea8b8115298fbc89c2e02db197/items/3a4eabf78592d969a1115ac5b3c8116a3175a17b"
   }
]

3.7.6. Edit feed meta data

Example request body:

{
   "title": "New title",
   "meta": {
      ...
   }
}

3.7.7. Send new items to feed

Example request body:

{
   "title": "Title",
   "description": "Item description",
   "summary": "Item summary",
   "link": "http://example.com/1",
   "origlink": "http://example.com/1",
   "date": "2013-11-08T08:44:23.000Z",
   "pubdate": "2013-11-08T08:44:23.000Z", 
   "author": "",
   "guid": "http://yle.fi/uutiset/6923993",
   "comments": "",
   "images": "",
   "categories": ["One", "Two"],
   "source": "", 
   "enclosures": [
      {
         "length" : null,
         "url" : "http://img.yle.fi/uutiset/oulu/article6923966.ece/ALTERNATES/w205h115/081113+nen%C3%A4p%C3%A4iv%C3%A4+2013+rotuaari+villasukka+pellenen%C3%A4",
         "type" : "image/jpeg"
      }
   ],
   "meta": {
      ...
   }
}

You can also send more than one by sending an array instead:

[
  {
     ...
  },
  {
     ...
  }
]

3.7.8. Get single feed item

You will get this object as response:

{
   "source" : {},
   "pubdate" : "2013-11-08T08:44:23.000Z",
   "feed_id" : "884b15d1eb470eea8b8115298fbc89c2e02db197",
   "date" : "2013-11-08T08:44:23.000Z",
   "author" : null,
   "comments" : null,
   "meta" : null,
   "enclosures" : [
      {
         "length" : null,
         "url" : "http://img.yle.fi/uutiset/oulu/article6923966.ece/ALTERNATES/w205h115/081113+nen%C3%A4p%C3%A4iv%C3%A4+2013+rotuaari+villasukka+pellenen%C3%A4",
         "type" : "image/jpeg"
      }
   ],
   "summary" : "Nenäpäivän juhlijat valtasivat perjantaina Oulun kävelykatu 
Rotuaarin. Katso kuvia Nenäpäivän vietosta.",
   "guid" : "http://yle.fi/uutiset/6923993",
   "id" : "7cfcce756090b565fdc5b9132b0ea9a6be4f0290",
   "link" : "http://yle.fi/uutiset/oulun_rotuaari_muuttui_punanenaisten_kaduksi/6923993?origin=rss",
   "origlink" : null,
   "categories" : [
      "Oulu"
   ],
   "description" : "Nenäpäivän juhlijat valtasivat perjantaina Oulun kävelykatu 
Rotuaarin. Katso kuvia Nenäpäivän vietosta.",
   "image" : null,
   "title" : "Oulun Rotuaari muuttui punanenäisten kaduksi"
}

4. GET /auth

Some passport related APIs are located at https://reader.tidhr.com/auth/.

You will get this object as response:

{
   "facebook" : {
      "$ref" : "https://reader.tidhr.com/auth/facebook"
   },
   "github" : {
      "$ref" : "https://reader.tidhr.com/auth/github"
   },
   "local" : {
      "$ref" : "https://reader.tidhr.com/auth/local"                                                                                                                             
   }                                                                                                                                                                             
}

If a property...

4.1. Login by local authentication

Example JSON request body:

{
   "username": "john",
   "password": "12345678"
}

This will create a Cookie based session.

4.2. Logout


A. Appendix


A1. How to use CURL

Save settings to .netrc and use curl -n -H 'Content-Type:application/json' -X method URL.

Example .netrc file:

machine reader.tidhr.com
  login 1u766KPuWTP0fSJJzs62gtAd5YXQpQ4X
  password LAajuGRpbYdaorxgh5u5q3EtaajWowqG