The AtomSphere API provides programmatic access to functionality that is normally accessed through the Dell Boomi AtomSphere platform.
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 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 your integration 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.
Using 2FA with the AtomSphere API
When making calls to the AtomSphere API, users with two-factor authentication (2FA) enabled are required to include X-Boomi-OTP as the REST or SOAP Security header and set a valid authentication code as its value. For more information about using two-factor authentication, see Two-factor authentication and its related subtopics.
The following example call includes the 2FA HTTP header and authentication code, where XXXXXX is the six-digit authentication code generated from the authenticator application.
curl -X POST -u firstname.lastname@example.org:password1 -H "X-Boomi-OTP:XXXXXX" -H "Content-Type: text/html" https://api.boomi.com/api/rest/v1/boomi-internal/AuditLog/query -d@queryPayload.xml
The following example call includes the 2FA SOAP Security header and authentication code, where XXXXXX is the six-digit authentication code generated from the authenticator application.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.platform.boomi.com/"> ... <soapenv:Header> <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"> <wsse:UsernameToken wsu:Id="UsernameToken" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"> <wsse:Username>email@example.com</wsse:Username> <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">password1</wsse:Password> </wsse:UsernameToken> <api:X-Boomi-OTP>XXXXXX</api:X-Boomi-OTP> </wsse:Security> </soapenv:Header> <soapenv:Body> ... </soapenv:Body> </soapenv:Envelope>
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.
The AtomSphere API connector and AtomSphere Partner API connector handle the HTTP 503 errors automatically by retrying a request up to five times.