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.
**Please note: Use of the API is monitored and abuse will result in privilege suspension and further investigation.**