Resources

Dealing with note attachments


Overview

Resources represent files that are embedded within a note. Common resource types include images, audio clips, PDFs, and documents, but any type of file can be stored in a Resouce.

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:

$resource = $noteStore->getResource($authToken, $resourceGuid, true, false, true, false);
$fileContent = $resource->data->body;
$fileType = $resource->mime;
$fileName = $resource->attributes->filename;
view raw example.php hosted with ❤ by GitHub
- (void)getResourceWithGUID:(NSString*)resourceGUID {
[[EvernoteNoteStore noteStore] getResourceWithGuid:resourceGUID withData:YES withRecognition:NO withAttributes:YES withAlternateDate:NO success:^(EDAMResource *resource) {
NSData* fileContent = resource.data.body;
NSString* fileType = resource.mime;
NSString* fileName = resource.attributes.fileName;
} failure:^(NSError *error) {
NSLog(@"Error : %@",error);
}];
}
view raw gistfile1.m hosted with ❤ by GitHub
resource = note_store.getResource(resource_guid, true, false, true, false)
file_content = resource.data.body
file_type = resource.mime
file_name = resource.attributes.fileName
view raw example.rb hosted with ❤ by GitHub
resource = note_store.getResource(resource_guid, True, False, True, False)
file_content = resource.data.body
file_type = resource.mime
file_name = resource.attributes.fileName
view raw example.py hosted with ❤ by GitHub
Resource resource = noteStore.getResource(resourceGuid, true, false, true, false);
byte[] fileContent = resource.getData().getBody();
String fileType = resource.getMime();
String fileName = resource.getAttributes().getFileName();
view raw example.java hosted with ❤ by GitHub
noteStore.getResource(resourceGuid, true, false, true, false, function(resource) {
var fileContent = resource.data.body;
var fileType = resource.mime;
var fileName = resource.attributes.fileName;
});
view raw example.js hosted with ❤ by GitHub

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:

$userInfo = $userStore->getPublicUserInfo($username);
$resGuid = '8528dddd-1d71-4e4d-9006-377be7517dfb'; // example GUID
$resUrl = $userInfo->webApiUrlPrefix . '/res/' . $resGuid;
view raw example.php hosted with ❤ by GitHub
- (void)downloadResourceExampleWithUserName:(NSString*) userName
withResourceGUID:(NSString*) resourceGUID{
[[EvernoteUserStore userStore] getPublicUserInfoWithUsername:userName success:^(EDAMPublicUserInfo *info) {
NSString * resourceURL = [NSString stringWithFormat:@"%@/res/%@",[[EvernoteSession sharedSession] webApiUrlPrefix],resourceGUID];
NSLog(@"Resource URL : %@",resourceURL);
} failure:^(NSError *error) {
NSLog(@"Error : %@",error);
}];
}
view raw gistfile1.m hosted with ❤ by GitHub
user_info = user_store.getPublicUserInfo(username)
res_guid = '8528dddd-1d71-4e4d-9006-377be7517dfb'
res_url = "#{user_info.webApiUrlPrefix}/res/#{res_guid}"
view raw example.rb hosted with ❤ by GitHub
user_info = user_store.getPublicUserInfo(username)
res_guid = '8528dddd-1d71-4e4d-9006-377be7517dfb'
res_url = "%s/res/%s" % (user_info.webApiUrlPrefix, res_guid)
view raw example.py hosted with ❤ by GitHub
PublicUserInfo userInfo = userStore.getPublicUserInfo(username);
String resGuid = "8528dddd-1d71-4e4d-9006-377be7517dfb";
String resUrl = userInfo.getWebApiUrlPrefix() + "/res/" + resGuid;
view raw example.java hosted with ❤ by GitHub
userStore.getPublicUserInfo(username, function(userInfo) {
resGuid = "8528dddd-1d71-4e4d-9006-377be7517dfb";
resUrl = userInfo.webApiUrlPrefix + "/res/" + resGuid;
});
view raw example.js hosted with ❤ by GitHub

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:

POST /shard/s1/res/8528dddd-1d71-4e4d-9006-377be7517dfb HTTP/1.1
Host: www.evernote.com
Content-Length: 99
Content-Type: application/x-www-form-urlencoded
auth=S%3Ds1%3AU%3D293f%3AE%3Db46cda%3AC%3D12e5d64584d%3AP%3D37%3AA%3Dfred%3AH%3D50a022dd072798e192
view raw example.txt hosted with ❤ by GitHub
Stay on top of what's happening in the Evernote developer community.
Complete the form below to open a support request with the Evernote Developer Relations team.
Important: we are ending access to the Sandbox environment from November 15, 2023. Use this form to request your Sandbox API keys to be promoted to production.

Please explain how your application
uses create, read, and update permissions.
Complete the form below to have your integration considered for inclusion in the App Center.
Complete the form below to request your complimentary 1-year Squarespace account.