The AtomSphere API provides programmatic access to functionality that is normally accessed through the AtomSphere application.
The API is built around an object/verb hierarchy. This hierarchy parallels the basic object-oriented programming paradigm as well as the web service implementation behind REST. Within the AtomSphere API:
Objects represent structures and relationships within AtomSphere, such as Account, Account User Role, Atom Startup Properties, and Environment.
Verbs are the various operations that you can perform for each object, such as GET, QUERY, and UPDATE. These verbs are referred to as object-based operations. Verbs that do not fall into the object/verb hierarchy, such as deployComponent and executeProcess, are referred to as action-based operations.
All AtomSphere API calls are authenticated by AtomSphere user name and account ID. The account ID is used as the general context for any API call. For example, if you make an API call to execute a QUERY of the Account Groups object with no query filters applied, all of the account groups owned by the authenticated account are returned.
The AtomSphere API has been developed with both a RESTish and a SOAP implementation.
The AtomSphere Partner API, which supports additional partner-specific operations.
The AtomSphere API and AtomSphere Partner API connectors, which enable you to perform API object-based operations and actions within AtomSphere processes.
All RESTish API endpoint URLs begin with the following prefix:
where accountID is your AtomSphere account ID. The full endpoint URL is dependent upon the operation you are trying to perform. Complete URLs are provided in the description of each API object-based operation and action.
RESTish requests are protected by HTTP Basic Authentication, so your AtomSphere user name and password are required.
Request and response bodies for RESTish requests are XML by default. The XML schema, which is the same for both the RESTish API and the SOAP API, is located at:
You can use JSON-formatted request bodies in RESTish calls by sending the request with the following HTTP header:
To receive JSON-formatted responses, send the request with the following HTTP header:
The SOAP API's WSDL (Web Services Description Language) is located at:
where accountID is your AtomSphere account ID.
The WSDL is protected by HTTP Basic Authentication, so your AtomSphere user name and password are required to access it. The XML schema, which is included in the WSDL by reference, is also protected by HTTP Basic Authentication. Each SOAP request is protected by WS-Security using a UsernameToken where the password is passed as PasswordText.
API usage limits
Both the RESTish and SOAP implementations of the AtomSphere API enforce the following usage limits.
|Number of requests per day|| The limit is account-specific. |
Your account’s usage request limit is calculated as 1000 times your number of licensed connectors. Usage is calculated based on a rolling 24-hour period with usage calculated every hour. If usage of the API exceeds this limit, API users receive an HTTP 503 response indicating that the server is temporarily unable to fulfill the request.
For a simple example of how this works, assume that your account has a limit of 200 requests per day. If, starting at 12:00 P.M. on Monday, API users make 10 requests per hour, the account will reach it's limit of requests per rolling 24-hour period during the 7 A.M. hour on Tuesday (20 hours * 10 requests/hour = 200 requests). API users will not be able to make requests again until the previous 24-hour period has fewer than 200 requests. That threshold will be reached after 12:00 P.M. on Tuesday, when the previous day's requests fall out of the previous 24-hour period.
|Rate of requests per second|| The limit is five requests per second. |
If API usage exceeds this limit, API users receive an HTTP 503 response indicating that the server is temporarily unable to fulfill the request.