Best Practices

Using Access Tokens

Once you have an API key, your next step is to use that key to authenticate to get an access token to use for all API requests. Please check the authentication documentation page to see how to authenticate for your type of key and application.

Once you get a token, you must cache it for use in regular API calls rather than making a token request each time you make an API request. Though tokens do not expire, tokens will stop working if a user changes their password.

All API actions are executed within the permission context of the user. You can only access resources (e.g. files or folders) that the user has permissions to access. If you are using an administrative account, you can optionally use a feature called User Impersonation to perform an action on behalf of a user. Impersonated calls are executed in the context of the user being impersonated and are noted in our audit reports as impersonated calls.

Rate Limiting

Our API rate limits restrict both the number of calls per day and number of calls per second. Our API rate limits and daily usage limits are enforced per access token rather than against the entire key. So, even if one user exceeds their quota under your key, other users will still be able to access Egnyte through your application. Integrations should be built with inherent support for receiving and handling these throttles. The default settings for all tokens issued under a key are:

Description Limit
API Key 1,000 API calls per day per token
2 API calls per second per token
OAuth token endpoint (Public app flow) 100 token requests per hour
OAuth token endpoint (Internal app flow) 10 token requests per user per hour

If you anticipate that your API call volume will exceed these limits when your application is in production, please contact us and we can discuss other arrangements.

If your API call is throttled you will see a response with a 403 HTTP status code with one of two possible values for the X-Mashery-Error-Code header field:

Error Description
ERR_403_DEVELOPER_OVER_QPS Exceeded per second throttle
ERR_403_DEVELOPER_OVER_RATE Exceeded daily quota

The Retry-After header will be set to the number of seconds until the relevant throttle will next be reset.

In addition to the general API endpoint rate limiting, the OAuth token endpoint (/puboauth/token) is also rate limited. For the Publicly Available Application authentication flow, the limit is 100 token requests per hour. For the Internal Application authentication flow, the limit is 10 calls/user/hour. When throttled, you will see a response with a 409 HTTP status code. The Retry-After header will be set to the number of seconds until the throttle will next be reset. In general, you will not encounter this limit since you should be requesting a token only once per user and persisting it rather than requesting a token repeatedly.

Formats

File System Paths in URLs

When you're putting file paths in URLs, the individual elements of folder paths in the URL must be URL encoded. However the intervening forward slashes must not be escaped. For example, this path: /Shared/example?path/$file.txt should be encoded as /Shared/example%3Fpath/%24file.txt. This is particularly important for the file system and permission API endpoints.

Timestamps

Dates and times are in ISO 8601 format. For example, May 27, 2014 is represented as 2014-05-27. Similarly 10:27:01pm on May 27, 2014 is represented as 2014-05-27T22:27:01Z.

Impersonation

Public API allows admin users to impersonate any other user by providing their username or e-mail address associated with the account. To impersonate, you need to make an API call with OAuth token of an admin user and one of the following headers.

X-Egnyte-Act-As: username X-Egnyte-Act-As-Email: email

You only need one of the headers. If two are provided, X-Egnyte-Act-As-Email will be ignored.

Impersonation Example to Create Folder

POST /pubapi/v1/fs/Shared/test HTTP/1.1
  Host: apidemo.egnyte.com
  Authorization: Bearer 68zc95e3xv954u6k3hbnma3q
  Content-Type: application/json
  {
  	"X-Egnyte-Act-As-Email": "test@test.com"
  }
curl -v -X POST -H "Authorization: Bearer 68zc95e3xv954u6k3hbnma3q" -H "Content-Type: application/json" --data '{"X-Egnyte-Act-As-Email":"test@test.com"}' https://apidemo.egnyte.com/pubapi/v1/fs/Shared/test

Common HTTP Headers

HTTP Request Headers

Header Value Description
Content-Type application/json Specifies the format of request body
Authorization Bearer {OAuth token} This must use the the OAuth token you obtained through the OAuth flow.

HTTP Response Headers

Header Value Description
Content-Type application/json Specifies the format of request body

Common Response Codes

HTTP Code Description
200 Successful operation
201 Successful creation
204 Successful creation with no response body content
400 Request is syntactically incorrect
401 Authentication failure
403 Authorization failure
404 Item or path not found
409 Conflict with an existing resource.

Error Messages

Errors are returned in the HTTP Status Code of the response. The response body also includes an array of errors that provide a more descriptive description of the error. If multiple errors were found, the API will include multiple entries.

HTTP/1.1 404 NOT FOUND

{"Errors": [{"description": "Link does not exist.","code": "404"}]}