This document describes how to use the AceProject API to develop your own tools to retrieve and manage your data. This guide is intended for developers and includes information about using the API as well as access to the API Explorer with code samples. Do not hesitate to contact us should you require additional information or technical support.
The API is always under development. Changes to the data model and to functions often occur, but we do our best to minimize the impact of such modifications. We can’t guarantee that external tools developed using this API won’t need extra development after a new version of the API is released.
Table of contents
To start using the AceProject API, you need:
- Your Account Name: Your account name (AccountId) is the subdomain found in the URL (http://account.aceproject.com). If you do not have an account, you can create one for free here.
- A Login name: A Username: a valid username associated to an active user within the account.
- A Password: a valid password associated to the provided username.
Getting Public Settings
- The GetPublicSettings function returns various public fields with information about the account.
Getting a GUID
- The Login function requires a valid username and password for an active user within the account.
- The function returns a GUID with various user related information. The GUID necessary for all other calls to the API. It is valid for a predetermined period of time and will then automatically expire after 8 hours of inactivity.
Parameters: Data types and formats
The API uses various data types and formats. Here are a few important details when calling and using the API
- Dates must always be provided using the following format: YYYY-MM-DD. For example, 23 Febuary 2011 would be 2011-02-23.
- Hours use 0 through 24 standard.
- Time must always be provided using the following format: HH:MI:SS. For example, 13:20:55
- When used with dates, hours will be provided in this format: YYYY-MM-DD HH:MI:SS
- Decimal values must always be sent with a period (.) as the decimal separator and do not require hundred separators. Do not use comma, space or any other character.
Non mandatory parameters vs. empty values
- When a parameter is non mandatory and you do not wish to provide or change a value for the parameter, do not mention it within the querystring when calling the API.
- If you want to pass an empty value for the parameter, you must use parameter=NULL.
- Some parameters have predefined default values. Default values can be specific settings or NULL when a parameter is non mandatory.
- When retrieving the function examples through the API Explorer, default values are automatically set in the HTTP Get example code. You can change theses values to any valid input when needed.
You can provide, for each call, a desired format.
- Dataset: format=ds
- RecordSet: format=rs
- JSON: format=json – Still BETA, no support provided
When the API returns an error, different message types are predefined. Check the MESSAGE_TYPE column for one of these types.
- MSG_FUNCTIONAL: Returned when a user inputs invalid data.
- MSG_LOGOUT: Returned when the provided GUID is expired or invalid.
- MSG_PERMISSION: Returned when the user doesn’t have sufficient privileges to access the function or related data.
- MSG_TECHNICAL: Returned when a technical problem occurs within the API. This can happen if the database is unavailable or an unexpected behaviour occurs within the API code. For hosted accounts, an email with detailed error information is sent to the AceProject technical staff. For Intranet versions, error messages are logged either in the Windows Event Log or in a log file located in the files folder of the Intranet installation.
- MSG_MESSAGE: This message type is used to send feedback to the calling application. It is typically used for information purposes and does not mean an error has occured.
Timezones are now automatically managed in AceProject through the API. Each account has a defined timezone and each user can either use the account default timezone or specifies its own. Upon login, the GUID is linked to the user, thus the API knows what timezone is currently in use by the user for each call. When providing date and time values, the API will convert time to UTC and save that value in the database. When retrieving information from the database, the API will convert the UTC time to the user’s timezone. There is no need for any conversions on the client end as long as the appropriate GUID is being used.
Here is a list of available API functions to access and manage data within your AceProject account. Click on the function name to access the API Explorer which provides detailed information about the parameters and sample .Net code.