The API is designed using [RESTful principles](http://en.wikipedia.org/wiki/Representational_State_Transfer): objects (resources) are identified by URLs, and actions are specified by HTTP verbs (if you don’t understand what this means, don’t worry about it, it is not necessary for use of the API). URLs for the API closely mirror the URLs of the web application.
Similarly to the CDD web application, access to data using the API is scoped by vault. Most API URLs contain a vault identifier.
The majority of API calls return a [JSON](http://en.wikipedia.org/wiki/JSON) structure as the response body.
### Object IDs
Vaults, saved searches, and other objects are identified by an integer ID number. When you get a list of objects (vault names, saved searches, projects, etc) through the API, each object will have both a name and an ID. You may need to supply the numeric IDs in subsequent API calls. Some parameters take lists of objects, which are expressed using a comma-separated list of IDs.
Note that the same IDs are used in URLs for the CDD web interface, and you can in some cases copy numbers from there to API calls.
Consistent with CDD’s commitment to data privacy and safety, the CDD API uses a number of industry-standard mechanisms to ensure the security of your data. Described in more detail below, these include the use of secure network protocols, token-based authorization, and adherence to vault and project permission levels.
#### Secure network protocol
All API calls must be done using HTTP over SSL (Secure Sockets Layer). Sending all API calls via SSL ensures that all information, including the user's token, is sent in encrypted form.
#### Access Control
API access to data is controlled at several levels. First, a token must be obtained. See [Token-based Authentication](https://support.collaborativedrug.com/hc/en-us/articles/115005682263) for details on obtaining a token. Tokens are on a per user/account level. The user generated tokens are created with a specific role or set of capabilities. The actual capabilities depend on the token owner’s role relative to the vault(s) being accessed.
Even with a token, data can only be obtained from a vault to which API access has been enabled by the CDD Support team. To enable the API for your vault, the vault administrator should email [CDD Support](https://support.collaborativedrug.com/hc/en-us/requests/new).
At the next level, a user can only obtain data from projects to which they have access. A list of projects a user can access in a particular vault can be determined via an API call.
#### API Throttling and Rate Limiting Mechanism
We try to impose as few limits on API usage as possible, and we respectfully request that you optimize your integrations to use Vault's API efficiently. If any of the limits pose problems for you, or if you have feature requests that would make your API use more efficient, please let us know.
CDD Vault does not limit the total number of API requests you can make. We throttle API usage in a few ways:
**3 Concurrent Requests**
Each user can make as many as 3 concurrent requests. This means your API integration could use 3 separate threads or processes, with each one making new requests as fast as requests are completed. Note that this limit is per user, not per API key, which is important to keep in mind if you plan to run multiple API integrations.
**30 Queued Exports**
All API requests that use the async parameter, or download a saved search, launch a background export. CDD Vault will process up to three of these at a time for you, and the rest will be added to a queue. We limit the size of this queue to 30.
**Please note: Use of the API is monitored and abuse will result in privilege suspension and further investigation.**