memonic

Items Resource

The items resource represents a list all Items of a user. This is equivalent to using the SetItems resource with a set_id of __all__.

Resource URL: https://api.memonic.com/v2/users/{user_id}/items?apikey={yourkey}

MethodPurpose
GET Returns a paginated list with all Items of the user.
POST Creates a new Item in the user's collection without assigning it to a Set.

Table of Contents

  1. GET
    1. Request
    2. Response
  2. POST
    1. Request
      1. Request with attachments (inline)
      2. Request with attachments (multipart)
      3. fetch_source / Read Later
    2. Response

GET

The GET method on the items resource returns a list of all the user's Items.

Request

Query string parameters

ParamPurposeValidation
page The page to show from the paginated set. Default is 1 to show the first page. Numeric
pagesize Number of Items to include on one page. Default is -1 to show all the Items at once. Numeric

Response

Status codes

The following response status codes can be returned.

CodeReason
200 All good. Response body is enclosed.
401 Not logged in or invalid Authorization header.
404 The user does not exist.

In case of a successful 200 response the following output is returned:

XML

<items>
<item href="https://api.memonic.com/v2/users/user_id/sets/__all__/items/ccf50e93-6fc4-4e67-bdab-d3eb5696f9e9.xml?apikey=yourkey" order="0">
    <user>user_id</user>
    <link href="https://api.memonic.com/v2/users/user_id/items/ccf50e93-6fc4-4e67-bdab-d3eb5696f9e9.xml?apikey=yourkey" rel="canonical"/>
    <id>ccf50e93-6fc4-4e67-bdab-d3eb5696f9e9</id>
    <modified>2011-02-18T10:40:25</modified>
</item>
<item href="https://api.memonic.com/v2/users/user_id/sets/__all__/items/d370be14-d815-492d-b515-cdb6bd50f4ac.xml?apikey=yourkey" order="1">
    <user>user_id</user>
    <link href="https://api.memonic.com/v2/users/user_id/items/d370be14-d815-492d-b515-cdb6bd50f4ac.xml?apikey=yourkey" rel="canonical"/>
    <id>d370be14-d815-492d-b515-cdb6bd50f4ac</id>
    <modified>2011-02-16T18:22:52</modified>
</item>
<link href="https://api.memonic.com/v2/users/user_id/sets/__all__.xml?apikey=yourkey&amp;page=1&amp;pagesize=2" order="0" rel="self"/>
<link href="https://api.memonic.com/v2/users/user_id/sets/__all__.xml?apikey=yourkey&amp;page=1&amp;pagesize=2" order="1" rel="first"/>
<link href="https://api.memonic.com/v2/users/user_id/sets/__all__.xml?apikey=yourkey&amp;page=592&amp;pagesize=2" order="2" rel="last"/>
</items>

JSON

{
  "items": [
    {
      "user": "user_id", 
      "href": "https://api.memonic.com/v2/users/user_id/sets/__all__/items/ccf50e93-6fc4-4e67-bdab-d3eb5696f9e9.json?apikey=yourkey", 
      "link": {
        "href": "https://api.memonic.com/v2/users/user_id/items/ccf50e93-6fc4-4e67-bdab-d3eb5696f9e9.json?apikey=yourkey", 
        "rel": "canonical"
      }, 
      "id": "ccf50e93-6fc4-4e67-bdab-d3eb5696f9e9", 
      "modified": "2011-02-18T10:40:25"
    }, 
    {
      "user": "user_id", 
      "href": "https://api.memonic.com/v2/users/user_id/sets/__all__/items/d370be14-d815-492d-b515-cdb6bd50f4ac.json?apikey=yourkey", 
      "link": {
        "href": "https://api.memonic.com/v2/users/user_id/items/d370be14-d815-492d-b515-cdb6bd50f4ac.json?apikey=yourkey", 
        "rel": "canonical"
      }, 
      "id": "d370be14-d815-492d-b515-cdb6bd50f4ac", 
      "modified": "2011-02-16T18:22:52"
    }
  ], 
  "pagination": {
    "count": 1184, 
    "last": 592, 
    "pagesize": "2", 
    "first": 1
  }
}

POST

The POST method on the Items resource is used to create new Items. The Item will not be added to any Set but can be access through either this Items resource or the SetItems resource for the __all__ Set.

Request

The Item should be transmitted in the post body using the application/json or text/xml content type. The input is exactly the same as the XML or JSON Item response with one change: the id property must not be present. Additionally the key _uploads may also be present to add file attachments.

An example request:

POST /v2/users/user_id/items.xml?apikey=yourkey HTTP/1.1
Authorization: Basic dXNlcjpwYXNz
Host: api.memonic.com
Accept: text/xml
Content-Type: application/json
Content-Length: 126

{"permission": "private", "version": 1,
"data": {"source": "http://example.com/",
"body": "my body", "title": "My title"}}

Request with attachments (inline)

To upload attachments they can be added in the Item using the _uploads key. Each file is a dictionary with the keys content-type, name and content. The file contents must be base64 encoded and the content is the only required field of the three.

An example upload Item in JSON:

{
  "_uploads": [
    {
      "content": "base64(content_of_foo.png)", 
      "content-type": "image/png", 
      "name": "foo.png"
    }, 
    {
      "content": "base64(content_of_bar.png)", 
      "content-type": "image/png", 
      "name": "bar.png"
    }
  ], 
  "version": 1, 
  "data": {
    "body": "<img src=\"foo.png\">", 
    "source": "http://example.com/", 
    "title": "Item with attachments"
  }, 
  "permission": "private"
}

And the same Item but uploaded in an XML document:

<item>
<permission>private</permission>
<data>
    <body>&lt;img src=&quot;foo.png&quot;&gt;</body>
    <source>http://example.com/</source>
    <title>Item with attachments</title>
</data>
<version>1</version>
<_uploads>
    <file>
        <name>foo.png</name>
        <content-type>image/png</content-type>
        <content>base64(content_of_foo.png)</content>
    </file>
    <file>
        <name>bar.png</name>
        <content-type>image/png</content-type>
        <content>base64(content_of_bar.png)</content>
    </file>
</_uploads>
</item>

Request with attachments (multipart)

We provide the inline uploading of attachments because it's very easy to implement. But it comes with some overhead as all files need to be encoded in base64. To upload binary files it's more efficient to use multipart/form-data POST requests. In that case the Item XML or JSON representation is specified in the item field. All other form names are accepted as attachments and uploaded. You can also reference to those attachments using their file name from the Item's body HTML code.

An example request:

POST /v2/users/user_id/items.xml?apikey=yourkey HTTP/1.1
Authorization: Basic dXNlcjpwYXNz
Host: api.memonic.com
Accept: text/xml
Content-Type: multipart/form-data; boundary=----------------------------eb52ef0ec143
Content-Length: 1322

----------------------------eb52ef0ec143
Content-Disposition: form-data; name="item"
Content-Type: application/json

{"permission": "private", "version": 1,
"data": {"source": "http://example.com/",
        "body": "<img src="foo.png">",
        "title": "Item with attachments"}}
----------------------------eb52ef0ec143
Content-Disposition: form-data; name="file00"; filename="foo.png"
Content-Type: image/png

[Binary content of foo.png]
----------------------------eb52ef0ec143
Content-Disposition: form-data; name="file01"; filename="bar.png"
Content-Type: image/png

[Binary content of bar.png]
----------------------------eb52ef0ec143--

If you request the Item created like this from the API, you will get the following output:

{
  "attachments": [
    {
      "url": "http://attachmentdata.example.com/.../bar.png"
    }
  ], 
  "permission": "private", 
  "type": "item", 
  "created_at": "2011-02-16T18:22:40", 
  "updated_at": "2011-02-18T13:59:59", 
  "tinyurl": "http://mem.to/t/1phTt", 
  "version": "1", 
  "groups": [], 
  "sets": [
    {
      "id": "__all__"
    }, 
    {
      "id": "__inbox__"
    }
  ], 
  "data": {
    "body": "<img src=\"http://attachmentdata.example.com/.../bar.png\" />", 
    "title": "Item with attachments", 
    "screenshot.small": "http://memonicstatic.example.com/coverflow.png", 
    "source": "http://example.com/", 
    "screenshot.original": "http://attachmentdata.example.com/.../bar.png", 
    "screenshot.coverflow": "http://memonicstatic.example.com/coverflow.png"
  }, 
  "id": "d370be14-d815-492d-b515-cdb6bd50f4ac"
}

Note especially that foo.png was not added to the list of attachments as it is referenced from the body.

Creating multipart/form-data requests

Submitting a request using multipart/form-data content type can be difficult with some HTTP client libraries. Here is a list of recipes of how to achieve that with your language of choice:

fetch_source / Read Later

We provide a Read Later service. When you post an Item and include the fetch_source parameter, we will make an attempt to download the relevant content from the source URL.

An example for such an Item in JSON:

{
  "data": {
    "body": "The fallback body", 
    "source": "http://example.com/", 
    "title": "The fallback title"
  }, 
  "version": 1, 
  "fetch_source": true, 
  "permission": "private"
}

The downloading of the additional information is asynchronous and may take a moment. While Memonic is working its magic on the Item, the passed in title and body will be shown to the user. That title and body is also kept around if no data can be extracted from the source.

Response

Status codes

The following response status codes can be returned.

CodeReason
201 A new Item has been created.
400 The POST data was invalid.
401 Not logged in or invalid Authorization header.
402 Could not save the Item because the user is over her quota.
415 The input data was submitted using an unknown content type.

In case of a successful 201 response the following output is returned:

XML

<status>
<message>The item has been created.</message>
<id>88e13812-acc2-4b56-a3d6-05d502e01968</id>
</status>

JSON

{
  "message": "The item has been created.", 
  "id": "aec9bf39-07ae-4771-bcf3-e428cc27fc27"
}