REST

OpenWebReader can be used as a web service with the REST interface.

How

Authentication

There are actually two ways to authenticate yourself on the REST api.

The first one uses HTTP Basic Authentication, that means it is RESTful, but your password is sent in plain text. Take care about this, and try to use this authentification method over HTTPS.

The second one uses is not RESTful. It uses a two-phase approach. The first one is logging, which will put a cookie into the client. You will then be able to do whatever you want. The cookie is also in plain text but does not contains your password.

The request

All requests have to be formatted like this : http://domain.tld/PATH/TO/OpenWebReader/rest[/[do][/[id]]].

If no action is given, it will be set to 'index'. Also, if no id/gid/uid/ids are given, they will be set to 0.

For GET and DELETE HTTP method, no datas will be accepted.

For PUT HTTP method, if you need to send datas to OpenWebReader, you can use <datas> as an array.

We are accepting datas for this array either in JSON or XML format, relative to the Content-Type header (default is json).

The method

We have a support for four HTTP methods :

  • GET : get datas
  • POST : add datas
  • PUT : update datas
  • DELETE : delete datas

For those method, the following actions (and relatives required/optional arguments) are available.

  • GET :
    • get : Renders the datas associated to the id
      • id : required
    • getlastnews : Set the unread news count to <unreads>
    • getlivenews : Render the count of unreads news for a specific id
      • id : optional
    • getmenupartgroup : Render the category template for a specific id
      • id : required
    • getmenupartstream : Render the stream template for a specific id
      • id : required
    • getnewcontents : Render the contents of a new for a specific id
      • id : required
    • getnewdetails : Render the details of a new for a specific id
      • id : required
    • getopml : Export the feeds in OPML format
    • getrss : Render the RSS template related to the specified id
      • id : optional
    • getstream : Render news template from a specific stream with a specific offset. Example : http://domain.tld/PATH/TO/OpenWebReader/rest/getstream/[id]/[offset]/[sort]/[dir].
      • id : optional
      • offset : page offset, 1 to x, optional
      • sort : 'title' or 'pubDate' or 'status', optional
      • dir : 'desc' or 'asc', optional
    • getunread : Set the unreads news count to <page>
    • getusers : Render the list of the users
    • maintenance : Do some database cleaning/maintenance (level administrator required)
    • search : Render results from a search. Example : http://domain.tld/PATH/TO/OpenWebReader/rest/[search]/[id]/[keywords].
      • keywords : required
    • regenerateopmltoken : Render an OPML gateway token
    • regeneratersstoken : Render a stream gateway token
    • logout : Logout yourself
  • POST :
    • login : Auth yourself
      • tlogin : required
      • key : required
      • uid : required
    • editopml : Import feeds in OPML format
      • url : remote url [OR]
      • FILE/opml : a file
      • gid : id of the category to import to, optional. If no gid is given, we will import into default category.
    • editstream : Add a stream
      • url : required
      • name : optionnal
    • editstreamgroup : Add a category
      • name : required
    • edituser : Add a user (level administrator required)
      • login : required
      • passwd : optionnal
      • confirmpasswd : required if passwd is set
      • rights : 1 (=user) or 2 (=administrator, level administrator required), optionnal
      • lang : optionnal
      • email : optionnal
      • openid : optionnal
      • timezone : optionnal
  • PUT :
    • upnew : Mark new(s) as read
      • id : can be a new, a stream or a category, optionnal. If no id is given, we will mark as read all the news.
      • ids : optionnal. Array of news to mark as read.
    • rename : Rename a stream or a category
      • id : required
      • name : required
    • move : Move a stream from a category to another
      • id : required
      • gid : optionnal. If no gid is given, we assume to move the stream to the default category.
    • edituser : Edit a user (level administrator required if the edited user is not the logged user)
      • id : required
      • login : required
      • passwd : optionnal
      • confirmpasswd : required if passwd is set
      • rights : 1 (=user) or 2 (=administrator, level administrator required), optionnal
      • lang : optionnal
      • email : optionnal
      • openid : optionnal
      • timezone : optionnal
  • DELETE :
    • delete : Delete a new, stream, category or a user (need to be logged as an administrator) or yourself
      • id : optionnal. If no id is given we will delete everything related to the user
    • clearstream : Clear (delete new(s)) of a stream or a category
      • id : optionnal. If no id is given, we will delete all the news

The response

According to the HTTP Content-type header, we will output either JSON, XML or HTML. If no Content-type is given, we assume JSON by default.

If an entity is created, we will send a HTTP Location header pointing to the new entity and send it's id.

If entities related to the new entity are created, we will send their ids.

If more than one entity is created, we will send the ids.

On error(s), <error> and/or <errors> can be set.

OpenWebReader may return one of the following HTTP status code :

  • 200 OK
  • 201 Created
  • 204 No content
  • 304 Not modified
  • 400 Bad request
  • 401 Unauthorized
  • 403 Forbidden
  • 404 Document not found
  • 409 Conflict
  • 500 Internal server error
  • 503 Service unavailable