Items 1.2

Sanitation

The following attributes are not sanitized meaning: including them in your web application can lead to XSS:

• title
• author
• url
• enclosureMime
• enclosureLink

Get items

• Status: Implemented
• Method: GET
• Route: /items
• Parameters:

{
  "batchSize": 10, //  the number of items that should be returned, defaults to -1, new in 5.2.3: -1 returns all items
  "offset": 30, // only return older (lower than equal that id) items than the one with id 30
  "type": 1, // the type of the query (Feed: 0, Folder: 1, Starred: 2, All: 3)
  "id": 12, // the id of the folder or feed, Use 0 for Starred and All
  "getRead": true, // if true it returns all items, false returns only unread items
  "oldestFirst": false  // implemented in 3.002, if true it reverse the sort order
}

• Returns:

{
  "items": [
    {
      "id": 3443,
      "guid": "http://grulja.wordpress.com/?p=76",
      "guidHash": "3059047a572cd9cd5d0bf645faffd077",
      "url": "http://grulja.wordpress.com/2013/04/29/plasma-nm-after-the-solid-sprint/",
      "title": "Plasma-nm after the solid sprint",
      "author": "Jan Grulich (grulja)",
      "pubDate": 1367270544,
      "body": "<p>At first I have to say...</p>",
      "enclosureMime": null,
      "enclosureLink": null,
      "feedId": 67,
      "unread": true,
      "starred": false,
      "lastModified": 1367273003,
      "fingerprint": "aeaae2123"  // new in 8.4.0 hash over title, enclosures, body and url. Same fingerprint means same item and it's advised to locally mark the other one read as well and filter out duplicates in folder and all articles view
    }, // etc
  ]
}

Example

Autopaging would work like this:

• Get the first 20 items from a feed with id 12

GET /items:

{
  "batchSize": 20,
  "offset": 0,
  "type": 1,
  "id": 12,
  "getRead": false
}

The item with the lowest item id is 43.

• Get the next 20 items: GET /items:

{
  "batchSize": 20,
  "offset": 43,
  "type": 1,
  "id": 12,
  "getRead": false
}

Get updated items

This is used to stay up to date.

• Status: Implemented
• Method: GET
• Route: /items/updated
• Parameters:

{
  "lastModified": 123231, // returns only items with a lastModified timestamp >= than this one
                          // this may also return already existing items whose read or starred status
                          // has been changed
  "type": 1, // the type of the query (Feed: 0, Folder: 1, Starred: 2, All: 3)
  "id": 12 // the id of the folder or feed, Use 0 for Starred and All
}

• Returns:

{
  "items": [
    {
      "id": 3443,
      "guid": "http://grulja.wordpress.com/?p=76",
      "guidHash": "3059047a572cd9cd5d0bf645faffd077",
      "url": "http://grulja.wordpress.com/2013/04/29/plasma-nm-after-the-solid-sprint/",
      "title": "Plasma-nm after the solid sprint",
      "author": "Jan Grulich (grulja)",
      "pubDate": 1367270544,
      "body": "<p>At first I have to say...</p>",
      "enclosureMime": null,
      "enclosureLink": null,
      "feedId": 67,
      "unread": true,
      "starred": false,
      "lastModified": 1367273003,
      "fingerprint": "aeaae2123"  // new in 8.4.0 hash over title, enclosures, body and url. Same fingerprint means same item and it's advised to locally mark the other one read as well and filter out duplicates in folder and all articles view
    }, // etc
  ]
}

Mark an item as read

• Status: Implemented
• Method: PUT
• Route: /items/{itemId}/read
• Parameters: none
• Return codes:
• HTTP 404: If the item does not exist
• Returns: nothing

Mark multiple items as read

• Status: Implemented in 1.2
• Method: PUT
• Route: /items/read/multiple
• Parameters:

{
  "items": [2, 3] // ids of the items
}

• Returns: nothing

Mark an item as unread

• Status: Implemented
• Method: PUT
• Route: /items/{itemId}/unread
• Parameters: none
• Return codes:
• HTTP 404: If the item does not exist
• Returns: nothing

Mark multiple items as unread

• Status: Implemented in 1.2
• Method: PUT
• Route: /items/unread/multiple
• Parameters:

{
  "items": [2, 3] // ids of the items
}

• Returns: nothing

Mark an item as starred

• Status: Implemented
• Method: PUT
• Route: /items/{feedId}/{guidHash}/star
• Parameters: none
• Return codes:
• HTTP 404: If the item does not exist
• Returns: nothing

Mark multiple items as starred

• Status: Implemented in 1.2
• Method: PUT
• Route: /items/star/multiple
• Parameters:

{
  "items": [
    {
      "feedId": 3,
      "guidHash": "sdf"
    }, // etc
  ]
}

• Returns: nothing

Mark an item as unstarred

• Status: Implemented
• Method: PUT
• Route: /items/{feedId}/{guidHash}/unstar
• Parameters: none
• Return codes:
• HTTP 404: If the item does not exist
• Returns: nothing

Mark multiple items as unstarred

• Status: Implemented in 1.2
• Method: PUT
• Route: /items/unstar/multiple
• Parameters:

{
  "items": [
    {
      "feedId": 3,
      "guidHash": "sdf"
    }, // etc
  ]
}

• Returns: nothing

Mark all items as read

• Status: Implemented
• Method: PUT
• Route: /items/read
• Parameters:

{
    // mark all items read lower than equal that id
    // this is mean to prevent marking items as read which the client/user does not yet know of
    "newestItemId": 10 
}

• Return codes:
• HTTP 404: If the feed does not exist
• Returns: nothing