Getting started with APIs

Integration Personas

Aconex supports the following integration personas. The process to register an Aconex integration is different for each persona:

Oracle Aconex Customer (Customer)

Oracle Aconex Customers are paying or non-paying organizations that have an active Aconex organization and user accounts for their employees who use Aconex for their daily project management activities.  Customer integrations are built for internal use by the Customer and their employees.

Oracle Technology Partner (Partner)

Oracle Technology Partners are vendors that have registered with the Oracle PartnerNetwork (OPN) and who deliver, or intend to deliver, solutions to Oracle Aconex Customers.  Partners build integrations between Aconex and their own software application (or another software application, with approval from the other party) with the intention of entering a commercial arrangement with Oracle Aconex Customers.  Partner integrations can be published for use by Oracle Aconex Customers and their employees.

API Security

All requests to Aconex APIs must be made using HTTPS on port 443.  Any requests which are not performed over an encrypted channel will be rejected. 

Aconex APIs are stateless, meaning the caller must provide valid user credentials (or a token representing an authenticated user) as part of every request.

The user's account must be active and the user must have access to the data being accessed.

Two methods of user authentication are supported when calling Aconex APIs:

Open Authorization (OAuth)

The OAuth 2.0 authorization framework enables a third-party application to obtain access to secured APIs based on authorization provided by an authenticated user.  

The Oracle Construction and Engineering Lobby (or "Lobby" for short), provides an OAuth 2.0 implementation for all Oracle Smart Construction Platform applications, including Aconex.  This implementation is sometimes referred to as "Lobby OAuth".

OAuth is the preferred method for user authentication when calling Aconex APIs, as it provides the highest level of security by making use of an access token to identify the authenticated user.

See Implement OAuth for more detailed information about how to implement SCP OAuth to integrate with Aconex APIs.

Basic Authentication (Basic Auth)

Basic Authentication is a simple approach used to identify an authenticated user that requires both the username and password to be specified every time an API is accessed.

Basic Auth is supported by Aconex APIs, but is not recommended due to the low level of security in this approach.  Basic Auth does not support Two-Step Verification (2SV) or Single Sign-On (SSO) user accounts.

See Implement Basic Authentication for more detailed information about using Basic Auth to integrate with Aconex APIs.

Implement an Aconex API Integration

Every integration with Aconex APIs must be registered with Oracle and you will receive credentials that will be used to uniquely identify the integration.

Your first step is to determine what API Security method you wish to use, as the registration steps are different for each method.

Read Implement OAuth and Implement Basic Authentication to learn more about each method.

If you are still unsure, contact Oracle Support.

 

Oracle Aconex Customers

Customers have two options for testing their integrations before enabling them in production on their live projects:

• Oracle provides an Early Access (EA) environment for testing Smart Construction Platform integrations in a non-production environment
• Every Aconex instance has a Training & Practice project available for you to use. Your Oracle contact can arrange an invitation to it upon request.

Oracle recommends that you complete all your integration testing in the Early Access Environment before connecting to production.

Taking this approach, your integration journey would be:

1. Integrate with the Early Access (EA) environment.
2. Create an OAuth Client or an Integration ID in Early Access.
3. Complete your integration testing in Early Access.
4. Create an OAuth Client or an Integration ID in Commercial Production.
5. Go live in Production by deploying a separate production version of your integration with the new Client Credentials or Integration ID.

Otherwise, you could:

1. Create an OAuth Client or an Integration ID in Commercial Production.
2. Request access to the Training & Practice project.
3. Complete your integration testing using the Training & Practice project.
4. Go live by connecting to your live projects.

You can find API Developer Guides at REST API Documentation.

Oracle Technology Partners

Oracle Technology Partners must join the Oracle PartnerNetwork and complete their testing in the Early Access (EA) environment before publishing to production.  Having published your integration, it will be available to all users. 

Your integration journey will be:

1. Join the Oracle PartnerNetwork (https://www.oracle.com/partnernetwork/program/).
2. Integrate with the Early Access (EA) environment.
3. Create an OAuth Client in Early Access.
4. Complete your integration testing in Early Access.
5. Publish your integration to production.
6. Deploy a production version of your integration with the new Client Credentials
7. Advise your customers to add your integration to their Identity Provider Policy.

You can find API Developer Guides at REST API Documentation.

Versioning

Aconex APIs support versioning and an API request or request content may be different depending on the version used.

The version used is specified in the request headers and Version 1 is used by default (if no header is specified).

Versioning is used to avoid breaking changes in the APIs, allowing developers time to migrate to a new version at their own pace.  Eventually, older versions will be deprecated and finally removed.

Each API module (Mail, Documents, Projects, etc.) has its own version.

The version requested for GET and PUT requests is specified in the “Accept” header, per the table below.

The version used for POST requests is specified in the “Content-Type” header.  The “Content-Type” value for the entire payload must be “multipart/mixed”.  The “Content-Type” for the XML part contains the version value in table below and the header must be specified directly on the next line after the boundary identifier and after the header there must be an empty line before the XML payload.

Sample GET or PUT Mail API accept header for version 2: 

Accept: application/vnd.aconex.mail.v2+xml

Sample POST Mail API content-type for version 2:

... ------------------------------8d314ec2031d2eb Content-Type: application/vnd.aconex.mail.v2+xml  ...

Error Handling

Aconex APIs may return error codes that must be handled appropriately.  An error may be returned due to an incorrect request structure, a login failure, or internal system error.

All error responses have the same structure as shown in the example below (an exception would be the consolidated validation error response provided by version 3 of the mail creation APIs).

<?xml version="1.0" encoding="UTF-8"?>

<Error>
  <ErrorCode>CANNOT_SUPERSEDE_LOCKED_DOCUMENT</ErrorCode>
  <ErrorDescription>Cannot supersede document 6590 which is locked</ErrorDescription>
  <RequestID>g5g8l8dk</RequestID>
  <SystemTime>2010-02-09T16:13:44.208+11:00</SystemTime>
</Error>

Each error response will contain:

• an error status code
• a brief textual description,
• a request id
• the system time when the error occurred

It should also be noted that while an error description is provided to end users in the error response, it is not necessarily intended for display to clients who are using your third party application. Some of the error descriptions may be of a technical nature. Use the error code, along with the context of the operation, to devise a user friendly error message to end users who make use of your application.

While many errors are unique to individual API services, below is a list of errors that are common and can occur across all API services for all requests and should be handled appropriately.

Login/Authentication Errors

Request based errors

Performance Throttling

There are reasonable limits which apply to both volume and frequency of requests an API caller can make using Aconex web services. These limits have been put in place to ensure the quality of service is maintained for all, especially users of the Aconex web interface. The limits applied to Aconex API are based on the following conditions:

• The number of concurrent requests an organization can make
• The frequency in which requests can be made
• If these limits are exceeded, the system may return error responses as described in the table below.

Error Code	Description	HTTP Status Code
CONCURRENCY_THROTTLE_LIMIT_REACHED	The maximum number of concurrent requests the user can perform has been reached.	503
MAX_FREQUENCY_THROTTLE_LIMIT_REACHED	The frequency at which you are making requests to the web services API has exceeded the limit imposed by the server. You should make requests less frequently.	503

More information about performance throttling on Aconex APIs can be found at Aconex web services performance throttling.

Internationalization

Character encoding

Character encoding used in Aconex web services is UTF-8, both for request and response messages. Invalid input will be rejected.

Multi-lingual content

Content is returned in the format provided by end users without any language identification, therefore your application should use this content 'as is'.

Localization

It is possible to get some of the data returned by the web services based on locales supported by Aconex. Aconex web services will currently return data in the locale specified by the user's preferences. Currently there is no ability to request the locale to use with the request.

Technical Support

If you have a technical support query relating to Aconex web services, please contact Oracle Support.