You are here

Getting started with APIs

Find out about using Aconex data to integrate enterprise software applications or develop third party applications.

With Aconex APIs you can:

  • Integrate Aconex with other software applications such as EDMS, internal mail systems and more
  • Improve data quality and consistency
  • Reduce manual errors and increase efficiencies
  • Extract project information for data mining or reporting
  • Extract and archive project information

Introduction to Aconex Web Services APIs 

This developer's guide provides comprehensive information about Aconex web services for developers looking to integrate enterprise software applications or develop third party applications that make use of the data residing within Aconex. 

Technology 

Aconex web services are designed to be programming language and platform independent and use a RESTful implementation with common standards such as HTTPS, URL and XML. At a minimum, developers wanting to make use of Aconex web services should be familiar with the following technologies/concepts: 

REST Interface 

Aconex web services are based on the concept of REST (Representational State Transfer). To access the services, requests that comply with the HTTPS standard must be constructed and make use of REST principles.

XML 

Aconex web services currently return all responses in XML format, except for the OAuth Services which returns responses in JSON. 

Security 

Aconex web services are designed to be entirely stateless, meaning the caller must provide valid user credentials as part of every request. The authenticating user's account must be active, and the user must have access to the relevant project. All requests must also be over HTTPS on port 443. Any requests which are not performed over an encrypted channel will be rejected. 

Currently two types of authentication are supported: 

  • Basic Authentication 
  • OAuth2 

Note: For user accounts having enabled SSO (Single Sign On) or 2SV (Two Step Verification), only the OAuth2 can be used.   

Basic Authentication 

The username and password is to be provided in the request using Basic Authentication principles.

		Authorization: Basic BASE_64_ENCODED_USERNAME_AND_PASSWORD

Sample request header: 

		Authorization: Basic cG9sZWFyeTpBdXRoM250MWM=

Below is an example using curl (a command line based Unix tool to perform web requests) to perform a mail search on the inbox of a project: 

		curl -u user:password https://{hostname}/api/projects/{projectid}/mail?mail_box=inbox

Here, username and password refer to the username and password used to logon to Aconex. Using standard clients such as curl, wget (or any programming library) will usually encode the username/password automatically using base64 encoding.

OAuth2

An access token is used in the request header: 

Authorization: Bearer ACCESS_TOKEN

An access token can be acquired using the Aconex API OAuth2 Services described in this specification. This involves a step where the user authorizes the application to be given access. Along with the access token is a refresh token. With the refresh token, the access token can be renewed indefinitely unless the user’s granted access is revoked. Learn more about OAuth.

Sample request header:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjEifQ.eyJlbWFpbCI6ImFodXNzZWluIiwiZXhwIjoxNDQwMTUyMzYxLCJzY29wZSI6W10sImNsaWVudF9pZCI6ImGwaXRlc3QifQ.Y0PH3VLnRpXp_95mEL40bbBfJLq1cnU3aHMwyGYiJVttpBFfh-0v7uJWlaSDK2SnU5YLH7DJHk-_454TMIJkZHQRxln4hwJTaXPqrpp1_vffJjXkIBd0piA6NahhDTdWsKHnG3uQxrNdy85fTp9KQgmD3KPXDUsfUomyQD8HsgTrwhm0r2WFIWz7xO_OMQlKI-ahYAi7GRReHS83B3SY_zxM_ZR15F16MCkvZ3e5ZkmsAbFsj9uVxzem2_2HwnJmV3dOLh7IAP1g16Q2syPeZI3Uqj17W3fkJieQOmyqiCJ8M9h-2gUYdF4evVg30vFo4ZkAPXo1QkrFyf2a8db6sg

How do I request an OAuth client?

Send an email to ecosystem_grp@oracle.com requesting an OAuth client with the following details:

  • Your Organization Name 
  • Name and email of your technical contact (if this is you, just add your details) 
  • Aconex instances used. (for example, AU1, UK1).
  • Redirect URI (if not specified, the default value of http://localhost:8089/callback will be used)

Project API Access

How can I request an API Key?
To have access to Aconex project data using Aconex API services, please contact your Oracle Aconex representative to request one. Each API application in use requires its own application key.

Using an API application key, the key is added to the request header:

X-Application-Key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx


For Field APIs, use X-Application:
X-Application: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Versioning

Aconex API services supports versioning. A request response or a request content can be different dependent on the version used. The version used is specified in the request headers. Version 1 is used by default. Versioning is used to avoid introducing breaking changes in the API services, allowing developers time to migrate to a new version at their own pace. Eventually, older versions will be depreciated and finally removed.

Different groups of API services (Mail, Document, Project, etc.) has its own version. All current API services has a default version 1 set.

The version requested for GET and PUT method services is specified in the “Accept” header, see value in below table. The version used for POST method services 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 below table, the header must come directly on the next line after the boundary identifier used and after the header there must be an empty line before the XML payload.

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

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

Sample POST Mail Services content-type for version 2:

... ------------------------------8d314ec2031d2eb Content-Type: application/vnd.aconex.mail.v2+xml  ...
Group VersionValue Comment
Mail1None or "application/xml"Default
Mail2"application/vnd.aconex.mail.v2+xml"-
Mail3"application/vnd.aconex.mail.v3+xml"-
Document1None or "application/xml" Default
Directory1None or "application/xml" Default
Projects1None or "application/xml" Default
Tasks1None or "application/xml" Default

Call Basics

Every call to an Aconex web service must include authentication information as detailed in the Security section of this document. Calls for each service will be different and require service-specific parameters to be provided. The common base path for all Aconex web services is below:

https://{hostname}/api/

For simplicity some examples of web service calls are shown below:

     1. Search the mail inbox for project id '100' on the organization user 'jdoe' is a member of

curl -u jdoe:s3cr3t https://{hostname}/api/projects/100/mail?mail_box=inbox

     2. Search the register for project id '100' on the organization user 'jdoe' is a member of

curl -u jdoe:s3cr3t https://{hostname}/api/projects/100/register

     3. Get the document schema for project id '100' that user 'jdoe' is a member of

curl -u jdoe:s3cr3t https://{hostname}/api/projects/100/register/schema

Some Aconex web services expect POST content in the form of XML along with file data, (for example Register Document, and Create Mail). These requests must have a content type set to multipart/mixed and must conform to the structure defined in the Internet standard RFC 1521 - MIME (Multipart Internet Mail extensions). Each service that accepts multipart requests will have its own prerequisites and conditions. All multipart sections which contain binary file data must be base64 encoded.

Throughout this article, hostname refers to the unique address of the Aconex instance where the relevant project data resides. Aconex has multiple instances hosted around the world, so it is important you construct service calls to address the appropriate instance for your project.

Error Handling

Aconex web services 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 API's).

<?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

Some error codes can be returned by multiple services, while others will be unique to a specific service. Ensure the context of the error code is taken into consideration when analyzing the error. 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

Error CodeError descriptionHTTP Status Code
LOGIN_FAILEDThe login credentials provided failed the validation process400
ACCESS_FAILED_FOR_ORGThe organization of the user performing the request has not been provided with access to the Web Services API400
ACCESS_FAILED_FOR_PROJECTThe user performing the request has not been provided with access to the Web Services API on the specified project400
API_NOT_ENABLED_FOR_PROJECTAPI key is missing in request or The Web Services API has not been enabled for the project specified400
PROJECT_DISCONNECTEDThe project specified in the request has been disconnected400
PROJECT_NOT_ACTIVEThe project specified in the request has been de-activated400
ACCESS_FAILED_FOR_USERThe user performing the request has not been provided with access to the Web Services API400
USER_NOT_ON_PROJECTThe user performing the request is not on the specified project400
USER_ACCOUNT_LOCKEDThe user performing the request has had their account locked400
USER_ACCOUNT_DISABLEDThe user performing the request has had their account disabled400
USER_PASSWORD_EXPIREDThe user's password has expired and needs to be reset400
USER_PASSWORD_RESETThe user's password has been manually reset by an admin400
NO_SUITABLE_AUTHENTICATION_METH ODNo suitable authentication method was found in the request, i.e. basic authentication headers were not present400
TWO_STEP_VERIFICATION_REQUIRED_ FOR_ACCESSUser requires 2-step verification to access Aconex403
SSO_REQUIRED_FOR_ACCESSUser requires SSO to login403

Request based errors

Error CodeError descriptionHTTP Status Code
INTERNAL_ERRORAn internal system error has occurred which was not expected500
INVALID_PARAMETER_VALUEA value provided for one of the query or path parameters was not valid400
OPERATION_DEPRECATEDThe version of this operation is no longer available405
OPERATION_NOT_SUPPORTEDThe operation targeted by the request could not be found405
PROJECT_NOT_FOUNDThe project specified in the path of the request was not found400
UNEXPECTED_PARAMETERA parameter provided in the request was not expected by the service being targeted400

An INTERNAL_ERROR may be returned by the system for a valid request. If this occurs, please contact Aconex via the API Support Forums and provide the following details to allow an investigation into the cause to be completed:

  • Aconex instance
  • requestId (from the error response)
  • date & time of the error

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 by the web services 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 with the following statuses:
Status CodeDescriptionHTTP Status Code
CONCURRENCY_THROTTLE_LIMIT_REACHEDThe maximum number of concurrent requests the user can perform has been reached.503
MAX_FREQUENCY_THROTTLE_LIMIT_REACHEDThe 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

Internationalization (i18n)

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 our Service Desk.

Was this article helpful?

Thanks. A ticket has been opened with the Support Central team.