Core Concepts

Evernote Cloud API Basics


The Evernote Cloud API is different than many web service APIs, but once you understand the basic patterns, it's easy to use.

The UserStore and the NoteStore

The Cloud API is comprised of two logical services: the UserStore and the NoteStore. The UserStore manages Evernote user accounts and is not typically used by third party applications. The NoteStore manages the contents of a user's Evernote account, and is the service that you'll access. This page introduces you to the basic patterns used to access the Cloud API. Once you understand these patterns, you can explore the reference documentation to find all of the APIs exposed by the NoteStore.

Before you can do anything useful with the Cloud API, you need to authenticate and gain access to a specific Evernote account. Authentication is explained in detail in the authentication chapter. Once you've authenticated successfully, you'll have two pieces of information that you need to access the NoteStore: the URL used to access NoteStore and an authentication token required to access the user's account. The NoteStore URL may differ by user, so it's important not to hardcode it or assume that it will always be the same.

Using the SDK

The Cloud API SDK contains wrapper libraries that you use to access both the UserStore and the NoteStore. To make NoteStore API calls, you need to create a NoteStore.Client object:

Aside from the User-Agent string, there's nothing that you need to change in the code above - it's all boilerplate. Check out the sample code in the SDK to see how to do this in other programming languages. To call an Evernote API function, simply invoke the appropriate method on the NoteStore.Client object that you just created:

The code above calls the NoteStore.listNotebooks function, which returns a list of Notebook objects. Notebook and other objects returned by the service are really just structures - containers for individual pieces of information that you can get and set. All of the actual API calls are invoked through the NoteStore.Client object. When you want to create a new object in an Evernote account, you instantiate an instance the appropriate data model object, fill in the fields that you want to set, then make your API call:

When you create a new object on the service, it returns a new instance of that object that contains the object's server-generated unique ID. You'll need this ID if you want to refer to the object later. You don't have to (and in fact can't) fill in these IDs ahead of time.

Now that you understand the basic patterns for using the Cloud API, you can use the remainder of the chapters in the documentation to see how to perform specific tasks.

Stay on top of what's happening in the Evernote developer community.