RestAPI

OAuth

Evernote OAuth process requires two steps: getting redirect url for authentication and getting access token.

Step1: Get Redirect Url

Request:

$ curl -X POST -d "callbackUrl=http://myapp/oauth-callback" http://localhost:8080/oauth/auth

Response:

{
  "authorizeUrl":"https://sandbox.evernote.com/OAuth.action?oauth_token=...",
  "requestTokenValue":"…",
  "requestTokenSecret":"…"
} 

In your application, you can redirect user to authorizeUrl. The redirect destination is an evernote authentication page. Your application needs to keep requestTokenValue and requestTokenSecret for next step.

Additionally, you can pass preferRegistration and supportLinkedSandbox parameters, and they will be appended to authorizeUrl as parameters.

Sample:

$ curl -X POST 
    -d "callbackUrl=http://myapp/oauth-callback"
    -d "preferRegistration=true" 
    -d "supportLinkedSandbox=true"
    http://localhost:8080/oauth/auth

Response:

{
  "authorizeUrl":".../OAuth.action?oauth_token=...&preferRegistration=true&supportLinkedSandbox=true",
  ...
} 

Step2: Get Access Token

After redirecting the user to the authorizeUrl and the user finished authorization on evernote page, the user will lead to the callbackUrl which was passed at first request. The callback-redirect-request contains oauth_token and oauth_verifier parameters. The oauth_token should match with the requestTokenValue from the first step response. Using those parameters, you need to call the /oauth/accessToken endpoint to obtain the access token.

Request:

$ curl -X POST -d "oauthVerifier=..." -d "oauthToken=..." -d "requestTokenSecret=..." http://localhost:8080/oauth/accessToken

• "oauthToken" is from callback request or first step response (they are identical).
• "requestTokenSecret" is from first step response
• "oauthVerifier" is from callback request

Reseponse:

{
  "value":"…",
  "secret":"",
  "edamShard":"s…",
  "edamUserId":"...",
  "edamExpires":"...",
  "edamNoteStoreUrl":"https://...evernote.com/shard/...",
  "edamWebApiUrlPrefix":"https://...evernote.com/shard/..."
} 

Evernote Operations

Two types of operations are defined in Evernote API. "UserStore" provides user related operations, and "NoteStore" provides note related operations.

In Evernote REST Webapp, all operations are mapped to this way: http://[server]/{userStore|noteStore}/{action}

As you can imagine, /userStore corresponds "UserStore" operations(services) and /noteStore corresponds to "NoteStore" operations. {action} is the target operation(a.k.a "service" in Evernote API).

When action takes parameters, you can pass them as JSON. Each parameter name corresponds to the keys in JSON. When parameter is another type, use another json object(a.k.a. hash or map)

• When parameter takes binary data, such as "body" field in "Types.Data", they need to be base64 encoded string in JSON.

Access Token

To specify access-token, your request needs to specify followings in http header.

• evernote-rest-accesstoken (required)
• evernote-rest-notestoreurl (optional)
• evernote-rest-webapiurlprefix (optional)
• evernote-rest-userid (optional)

Providing all parameters makes less evernote thrift calls in backend, thus performance is better. evernote-rest-notestoreurl, evernote-rest-webapiurlprefix, and evernote-rest-userid are optional but when you are providing, you have to provide all of them.

For development, you can specify developer token and related parameters in config file.

evernote.accessToken=[YOUR DEV TOKEN]
evernote.alwaysUseTokenFromConfig=true
evernote.fallbackToTokenFromConfig=true

When evernote.alwaysUseTokenFromConfig is set to true, regardless of evernote-rest-accesstoken in http header, it always use token from config file. If evernote.fallbackToTokenFromConfig is set to true, when http header doesn't have evernote-rest-accesstoken, it will use the developer token in config file.

URL and Parameter

URL and parameter are determined by the definition on Evernote API.

URL

URL is defined:

  /{userStore|noteStore}/{action}

All "Services" defined in Evernote API maps to the action url.
For example:

• UserStore.authenticate maps to /userStore/authenticate
• NoteStore.getNote maps to /noteStore/getNote

Parameter

When the target action takes parameters, they are specified by json.

You DO NOT need to provide "authentication token" in parameter. It is automatically filled by webapp based on the provided header value, evernote-rest-accesstoken or evernote.accessToken in config file.

For example, NoteStore.listTags is defined as:

list<Types.Tag> listTags(string authenticationToken)
    throws Errors.EDAMUserException, Errors.EDAMSystemException

The request will be /noteStore/listTags with no input parameter.

Parameter names are same as the ones in definition.

For example, NoteStore.getTag is defined as:

Types.Tag getTag(string authenticationToken,
                 Types.Guid guid)
    throws Errors.EDAMUserException, Errors.EDAMSystemException, Errors.EDAMNotFoundException

Types.Guid is essentially a string in definition.
guid is the key name in input json.

The request will be /noteStore/getTag.
Input parameter is:

  {  "guid" : "my-tag" }

Please reference these test case classes. They cover all actions with some json input parameters.

• StoreOperationControllerUserStoreIntegrationTest.java
• StoreOperationControllerNoteStoreIntegrationTest.java

UserStore Operations

All "UserStore" operations map to /userStore/{action}.

Sample urls are:

• http://localhost:8080/userStore/authenticate
• http://localhost:8080/userStore/checkVersion
• http://localhost:8080/userStore/getNoteStoreUrl
• http://localhost:8080/userStore/getUser

Please reference this test class which covers all "UserStore" actions with input JSON.

NoteStore Operations

All "NoteStore" operations map to /noteStore/{action}.

Sample urls are:

• http://localhost:8080/noteStore/copyNote
• http://localhost:8080/noteStore/createTag
• http://localhost:8080/noteStore/findNotes
• http://localhost:8080/noteStore/getResource
• http://localhost:8080/noteStore/updateNotebook

Please reference this test class which covers all "NoteStore" actions with input JSON.

• Binary data needs to be base64 encoded string in JSON.

Management Endpoints

Great benefit comes from spring-boot. The infrastructure information are provided by spring-boot-actuator endpoints.

Evernote REST Webapp sets default endpoint url to /management. This can be configured in config file propertymanagement.contextPath.

Available endpoints are:

• http://localhost:8080/management/info
• http://localhost:8080/management/dump
• http://localhost:8080/management/env
• http://localhost:8080/management/beans
• http://localhost:8080/management/metrics
• etc.

By default, the management endpoint is basic auth enabled by spring-boot. Default username is "user", password is randomly generated and shows up on start-up log at INFO level. You can change them in config file. management.security.enabled, management.security.user.name, management.security.user.password, etc.

Please reference spring-boot-actuator for more endpoint and configuration information.

Sample API Request

OAuth

• Get Redirect Url

$ curl -X POST -d "callbackUrl=http://myapp/oauth-callback" http://localhost:8080/oauth/auth

• Get Access Token

$ curl -X POST -d "oauthVerifier=..." -d "oauthToken=..." -d "requestTokenSecret=..." http://localhost:8080/oauth/accessToken

UserStore

• call "getUser"

$ curl -X POST 
      -H "Content-Type: application/json"  
      -H "evernote-rest-accesstoken: [MY_ACCESS_TOKEN]"
      http://localhost:8080/userStore/getUser

• call "getPublicUserInfo"

$ curl -X POST 
      -H "Content-Type: application/json"  
      -H "evernote-rest-accesstoken: [MY_ACCESS_TOKEN]"
      -H "evernote-rest-notestoreurl: https://sandbox.evernote.com/shard/s1/notestore"
      -H "evernote-rest-webapiurlprefix: https://sandbox.evernote.com/shard/s1/"
      -H "evernote-rest-userid: 1234567"
      -d '{ "username": "foo" }'
      http://localhost:8080/userStore/getPublicUserInfo

NoteStore

• call "findNotes"

$ curl -X POST 
      -H "Content-Type: application/json"  
      -H "evernote-rest-accesstoken: [MY_ACCESS_TOKEN]"
      -d '{
                "filter":{
                    "order": 2,
                    "ascending": true,
                    "words": "[NOTE_FILTER_WORDS]",
                    "notebookGuid": "[NOTEBOOK_GUID]",
                    "tagGuids": ["TAG_GUID1", "TAG_GUID2"],
                    "timeZone": "",
                    "inactive": true
                },
                "offset": 20,
                "maxNotes": 30
            }'
      http://localhost:8080/noteStore/findNotes

• call "createTag"

$ curl -X POST 
      -H "Content-Type: application/json"  
      -H "evernote-rest-accesstoken: [MY_ACCESS_TOKEN]"
      -H "evernote-rest-notestoreurl: https://sandbox.evernote.com/shard/s1/notestore"
      -H "evernote-rest-webapiurlprefix: https://sandbox.evernote.com/shard/s1/"
      -H "evernote-rest-userid: 1234567"
      -d '{
                "tag":{
                    "name":"TAG_NAME",
                    "parentGuid":"123456..."
                }
           }'                
      http://localhost:8080/noteStore/createTag