Resources

Dealing with note attachments

---

Creating resources

You'll notice that there's no NoteStore.createResource API call. This is because Resources don't exist outside of the context of a specific note. Instead, Resources are created implicitly when you include a new Resource object in a note as part of a call to NoteStore.createNote or NoteStore.updateNote. A note can have zero or more resources attached to it, with each resource containing the binary contents of the file and a set of optional metadata attributes such as the filename.

A resource is attached to a note by including it in the Note.resources list and referencing the resource from the note's ENML content using an <en-media> tag. Although it's technically possible to add a resource to Note.resources without including a corresponding <en-media> tag, there's no way for a user to view such a resource from an Evernote client app, and there's no guarantee that apps won't remove these "orphaned" resources.

See the chapter Creating notes for an example of how to create a new resource attached to a note.

Resource types

All Evernote client apps are capable of rendering image resources inline when displaying a note. Other resource types are displayed differently depending on the specific client that's displaying the note. For example, some clients will render a PDF in-line, while others will show a PDF icon that can be opened in an external viewer. Almost all Evernote client apps can display or allow the user to open the following basic set of resource types:

• image/gif
• image/jpeg
• image/png
• audio/wav
• audio/mpeg
• audio/amr
• application/pdf

Other resource types, such as documents, are typically displayed as a file icon. If there is an external application that is capable of opening the file type, it will be invoked when the user chooses to open the file.

Downloading resources

When you get a note through the Cloud API, it will contain the list of resources that are attached to that note. If you obtain the note using NoteStore.findNotes or NoteStore.findNotesMetadata, the note will contain only the resource metadata and not the actual binary file data. If you obtain the note using NoteStore.getNote, you can control whether the note that is returned contains the binary file data using the 'withResourcesData' parameter. If you have a note that contains only the Resource metadata, you can fetch the binary file data in two ways.

Downloading a resource through the API

To retrieve the full resource through the Cloud API, simply call NoteStore.getResource with the 'withData' field set to true:

It's important to note that filename is an optional resource attribute - some resources may not have a filename set.

Downloading a resource directly from the web

There's one serious catch to using the Cloud API to fetch resource data: the full file contents are downloaded to memory and can't easily be streamed. You can avoid this issue by requesting the resource directly from the Evernote service via an HTTP POST request. You'll first need to grab the webApiUrlPrefix value (which is returned with the OAuth response as well as by calling UserStore.getPublicUserInfo. Append /res/[resource GUID] to webApiUrlPrefix and you'll have the full URL of the resource:

This is the preferred method for constructing resource requests; those built this way will be forward-compatible.

The authentication token must be passed in order to access a resource that is not in a public shared notebook. The token is passed in a URL-encoded POST parameter named auth. Here's how the authenticated POST request for the resource with GUID 8528dddd-1d71-4e4d-9006-377be7517dfb looks: