Introduction
OneAegis has a number of APIs we collectively call the "XML APIs". These are a set of APIs that take a "request" as an XML document and return a "response" as another XML document. The simplicity of this request/response document model provides a consistent, robust, and traceable API model that supports the type of APIs many of our customers are looking for -- APIs that are configured once and then just run, silently, consistently, and successfully for years and years.
Request Structure
Invoking the XMLAPI is a simple HTTP POST of an XML document to the https://clientid.oneaegis.com/api/xmlapi endpoint (replacing 'clientid.oneaegis.com' with your specific client URL).
The XML document has a standard layout, with the 'payload' element contents varying from API to API:
<IRBManagerRequest>
<head>
<requestType>Note 1</requestType>
<requestingSystem>Note 2</requestingSystem>
<senderRequestId>Note 3</senderRequestId>
</head>
<payload>
Note 4
</payload>
</IRBManagerRequest>
Note 1 -- The "requestType" element value is a constant that tells us what API you're calling. This may be 'ContactExpirationsImport', 'AdhocReportApi', or any of a number of other values, but whatever the value, this value is a constant for the given API type.
Note 2 -- The "requestingSystem" element value is up to you, but we log it and it's useful to tell what system is consuming the API. This could be "HR Integration" or "LMS Updates", or whatever makes sense for you. While we don't care if you change this value from time to time the idea is that this value is consistent across all your calls to this API
Note 3 -- The "senderRequestId" element value should change from request to request. Again we use this in logging, but the idea is that this value represents a given invocation of the API. Guids are a great value to use here, just generate a new one for each invocation, but date/time works great here too. If you have an internal trace-id for this invocation just use that.
Note 4 -- The "payload" element is the meat of the API. The contents of this element will vary from API type to API type. It may be a list of contacts, xForm values, or ... it all depends on the specific API you're calling.
Response Structure
The XMLAPI will respond with an XML document similar to the request:
<IRBManagerResponse>
<head>
<!-- These reflect back what you sent -->
<requestType>xxx</requestType>
<requestingSystem>xxx</requestingSystem>
<senderRequestId>xxx</senderRequestId>
<!-- These are filled in by OneAegis on the response... -->
<IRBManagerRequestId>Note 1</IRBManagerRequestId>
<processDateTime>Note 2</processDateTime>
<elapsedTime>Note 3</elapsedTime>
<success>Note 4</success>
</head>
<payload>
Note 5
</payload>
</IRBManagerResponse>
The initial part of the IRBManagerResponse reflects back your request, so you're requesting system & request Id will be returned. We also add information to document our processing of the request including:
Note 1 -- The "IRBManagerRequestId" element will be a guid we generate on our side to represent this request. Each invocation will have a different guid, even if you send the same request to us multiple times.
Note 2 -- The "processDateTime" element will contain the timestamp (UTC) we received the API call and started handling it.
Note 3 -- The "elapsedTime" element contains the time (h:m:s.ffff) we took processing the API request.
Note 4 -- The "success" element is a boolean ('true' or 'false') indicating whether the API call "succeeded". The definition of success obviously varies from API to API, but this should be a good overall indication of outcome.
Note 5 -- The payload (if any) will vary from API to API.
Security
The security structure for the XMLAPI call is a simple one. You must identity yourself on every POST using simple BASIC auth. The username is in the format of "clientid\username" and the password is that user's password in OneAegis. However, the user must also be in the right group in OneAegis. In general this group is named 'api-access-xxx' where xxx is the name of the API (the requestType in the request). There are however some variations on this depending on the API. Generally speaking, the user invoking the API does not need any special (admin/staff/etc.) authority in OneAegis, the fact that they're a member of the group is sufficient for us to allow them to perform any actions appropriate to the API.
Failure Modes
As a simple HTTP request model, failures follow standard HTTP rules. Authentication failures will be reflected as 403 responses, any server-side errors (they happen), as 500-class errors. But otherwise the XMLAPI should return a 200 response and you should look at the "success" element to determine outcome. Depending on the API there may be information to discover out of the payload in the response too.
Notes
- The "IRBManager" in the API reflects an older product name for OneAegis, but for consistency, and to keep those older integrations working, we continue to use that name in the APIs.
- For clients still using the xxx.my.irbmanager.com domains, the API endpoint is https://clientid.my.irbmanager.com/api/xmlapi.
Comments
0 comments
Article is closed for comments.