Objective
This document is targeted to developers looking for connecting third-party applications with Airgile. Using this simple HTTP JSON/JSONP API, developers can easily read and write data from and to Airgile from other applications and user interfaces. This API can be used, for example, to:
- Send a new task to Airgile directly from a "report a bug" form in a custom website or application;
- Get specific tasks from Airgile and show them on a custom backoffice system automatically;
- Create custom reporting applications that read data from Airgile and show custom charts;
- Build custom user interfaces specific to certain businesses with different layouts or more features
- Manage the users in Airgile from other platforms. For example, an ERP application can be used to add new collaborators to the company, and those are automatically added to Airgile without further user interaction.
- Build custom Mobile (ex: iPhone or Android) or Web applications to add and list tasks (among other features)
- Share data between Airgile and other applications.
If you need more methods or to access more data, feel free to
contact us, we're open to improve the API. In case you need to connect Eclipse-based IDEs with Airgile, you should instead use our Mylyn gateway. Please see
this document.
This API documentation is currently only available in English.
Introduction to the API
The API consists in the use of simple HTTP requests (GET or POST) to well defined URLs, passing the data in the JSON or JSONP format. The data is returned as an HTTP response in the JSON format that can be easily parsed by pretty most any language or application.
A typical request to our API has the following format:
http://airgile.com/yourAccount/api/service/method?data={jsondata}
For example a call to:
http://airgile.com/webfuel/api/users/list
will returns all users in the “webfuel” account. The response will typically look like:
If there’s an error, the response will normally be:
You can test calls to the API by putting the request urls directly in your web-browser. If you need to pass parameters to your request simply append them to the query string in the JSON format:
http://airgile.com/webfuel/api/users/list?data={"projectID":4}
The above call returns only the users that are connected to the project with the ID 4. In some web-browsers you might need to urlencode the request:
http://airgile.com/webfuel/api/users/list?data=%7b"projectID"%3a4%7d
The API supports both JSON and JSONP formats automatically. If you're using jQuery, to choose one or the other format, specify the dataType ("json" or "jsonp") in the $.ajax call.
Our server will know when it's JSON or JSONP and return the answer in the proper format.
JSONP is a workaround for allowing cross-domain requests in web-browsers, since these are blocked by web-browsers without CORS support (like IE9). We advise you to use
JSONP if you're building a web-application that is supposed to run in all web-browser. Otherwise, you can use JSON.
Our API support both GET and POST methods in your AJAX calls and has a CORS implementation with session propagation with cookies for browsers supporting it.
Authentication
To start a new session with the API, simply make a call to:
http://airgile.com/acc/api/session/login?data={"email":"email@domain.com","password": "sha1pass"}
This method will return the logged in user and a sessionID, that you'll have to pass in all subsequent calls to maintain your session. You're not forced to pass the sessionID
in all calls, since our server has an implementation of CORS with cookie support, but since not all web-browsers support CORS we strongly recommend you use the sessionID. The complete documentation on the login method is available
here.
For security reasons, the third consecutive time you try to login with wrong credentials disables logging in for 15 seconds. You’ll receive an error with code 15. You’ll be able to call this service again 15 seconds later.
Below follows an example of a login with jQuery $.ajax:
$.ajax({url: "http://airgile.com/webfuel/api/session/login",
type: "GET",
dataType: "jsonp",
data: { data: JSON.stringify({ email: email,password: Crypto.SHA1(password)})},
success: function(data) {
if (data.status == 'OK') {
alert("Successful login by " + data.result.user.email);
alert("The sessionID is: " + data.result.sessionID);
} else
alert("Error in response: " + data.result);
},
error: function(req, text, error) {
alert("Error in the communication");
}
}
);
The password needs to be sent encrypted in SHA1. You can use the crypto-js for this purpose.
Code examples
Using Javascript and jQuery
Embed jQuery in the head of your HTML document by doing:
<script src="http://code.jquery.com/jquery-latest.js">
Then call the API using the $.ajax method, passing the sessionID in the call and your data in a stringified JSON:
$.ajax({url: "http://airgile.com/webfuel/api/tasks/list",
type: "GET",
dataType: "jsonp",
data: { sessionID: sessionID, data: JSON.stringify({projectID: projectID}) },
success: function(data) {
if (data.status == 'OK')
alert("Data arrived: " + data.result);
else
alert("Error in response: " + data.result);
},
error: function(req, text, error) {
alert("Error in the communication");
}
});
Here's a complete example, featuring logging in before other calls:
var sessionID = null;
function login(email, password)
{
$.ajax({url: "http://airgile.com/webfuel/api/session/login",
type: "GET",
dataType: "jsonp",
data: { data: JSON.stringify({ email: email, password: Crypto.SHA1(password)})},
success: function(data) {
if (data.status == 'OK') {
$("#loginStatus").html('Login Successful by ' + data.result.user.email);
sessionID = data.result.sessionID;
getUsers(4);
}
else
alert("Error in response: " + data.result);
},
error: function(req, text, error) {
alert("Error in the communication");
}
});
}
function getUsers(projectID)
{
$.ajax({url: "http://airgile.com/webfuel/api/users/list",
type: "GET",
dataType: "jsonp",
data: { sessionID: sessionID, data: JSON.stringify({projectID: projectID}) },
success: function(data) {
if (data.status == 'OK') {
var numUsers = data.result.users.length;
$("#numberOfUsers").html("Project " + projectID + " has " + numUsers + " users");
}
else
alert("Error in response: " + data.result);
},
error: function(req, text, error) {
alert("Error in the communication");
}
});
}
login('youremail@domain.pt', 'password');
Using PHP
<?
echo file_get_contents("http://airgile.com/acc/api/users/get?data={'userID':4}&sessionID=pirj3");
?>
Usage constraints
The API is only available to business, professional and enterprise accounts. To use the API, free and startup accounts need to be upgraded.
Blocked accounts naturally cannot access the API.
Session
http://airgile.com/acc/api/session/login
Receives
- password needs to be encrypted in SHA1. You can use crypto-js for this purpose
- If the login is invalid, an error with code 6 will be returned:
- For security reasons, the third consecutive time you try to login with wrong credentials disables logging in for 15 seconds. You’ll receive an error with code 15. You’ll be able to call this service again 15 seconds later.
- sessionID is a token that you have to pass to the server in all calls to make sure your session is maintained in web-browsers not supporting CORS. See how to use in the example above.
Returns
http://airgile.com/acc/api/session/logout
Receives
Nothing
Returns
Account
http://airgile.com/acc/api/account/get
Receives
Nothing
Returns
- alias is the unique name of your account (ex: http://airgile.com/alias)
- defaultLanguage can be either pt_PT or en_US
- usedDiskSpace is measured in bytes
Projects
http://airgile.com/acc/api/projects/list
Receives
- detailed is optional. If you omit it, you’ll receive a simplified list of projects (ID and name). If you force detailed to true, you’ll receive the complete information of projects
Returns
If you omit detailed:
If you force detailed to true:
- This service will only return the projects that can be accessed by the logged in user.
- archived can be true or false and indicates whether the project is in use, or is archived (not shown in the UI)
- emailNotificationsConfig is an int indicating that when a task is updated, all users will receive emails (0), only project managers will receive emails (1), or no one will receive emails (2)
- isTemplate indicates that this project is only used as a template to generate identical projects
http://airgile.com/acc/api/projects/get
Receives
Returns
- See projects/list for more info on each field.
- users is an array of the users connected to the specified project, with their corresponding role on the project.
- role field is only returned if the logged in user is an account administrator. Role can be: "Requester", "Participant", "Collaborator" and "Manager
- states, types, importances and milestones are arrays
- position is used to specify the order that the administrator specified for ordering these fields on the user interface
Users
http://airgile.com/acc/api/users/list
Receives
- projectID is optional. If you omit it, all users connected to the same projects of the logged in user will be returned. If you specify it, only the users connected to the specified project will be returned.
- detailed is optional. If you omit it, you’ll receive a simplified list of users (ID, name, pictureURL, updateDate). If you force detailed to true, you’ll receive the complete information of users
Returns
With "detailed: true"
- If you make the call without "detailed: true", only the basic fields will be returned.
- This service will only return the users that are somehow associated with the logged in user.
http://airgile.com/acc/api/users/get
Receives
Returns
- projects is an array of the projects that the user has permission to access, with the corresponding role for each project.
- role field is only returned if the logged in user is an account administrator. Role can be: "Requester", "Participant", "Collaborator" or "Manager"
http://airgile.com/acc/api/users/add
Receives
- This method is only available to account administrators.
- locale is the default language for that user. Can be: "pt_PT" or "en_US".
- projects is an array of "projectID" and "role". Role can be: "Requester", "Participant", "Collaborator" or "Manager"
- sendEmail indicates whether Airgile will send an email to this user with his password and account information
Returns
http://airgile.com/acc/api/users/set
Receives
- Only send the fields you want to change - if you omit a field, it's value will be kept unchanged. In other words, if you just need to change the password, simply send the above object only with the userID and password fields.
- sendEmail indicates whether Airgile will send an email to this user with his password and account information
- In the projects array, only send the projects where you need to change the role. In case you want to remove the user from a project, just put "None" in the role.
Returns
Tasks
http://airgile.com/acc/api/tasks/list
Receives
- updatedAfter is optional. If you specify it, only tasks updated after this date will be returned. The expected value is "AAAA-MM-DD HH:MM:SS".
- projectID is optional. If you provide it, only the tasks of the specified project will be returned.
- detailed is optional. If you omit it, you’ll receive a simplified list of tasks (taskID, title, inProjectID, updateDate). If you force detailed to true, you’ll receive the complete information of tasks
Returns
- If you make the call without "detailed: true", only the basic fields will be returned.
- This method will only return the tasks that the logged in user has permission to see.
- taskID is the internal ID of the task. This is what our system uses to identify a ticket, and is the ID you should use when getting, editing or deleting a task
- customID is a friendly identifier that the user sees, dependant on the project. Airgile users identify tickets by the following ID: "#inProjectID-customID"
http://airgile.com/acc/api/tasks/get
Receives
- taskID is the internal task ID (not the customID).
Returns
http://airgile.com/acc/api/tasks/add
Receives
- subscribedUsers is an array with the userIDs of the users that will receive an email from Airgile with the new task.
Returns
http://airgile.com/acc/api/tasks/set
Receives
Returns
http://airgile.com/acc/api/tasks/del
Receives
Returns
Tasks:Comments
http://airgile.com/acc/api/tasks/comments/list
Receives
Returns
http://airgile.com/acc/api/tasks/comments/add
Receives
Returns
http://airgile.com/acc/api/tasks/comments/del
Receives
Returns
Follow us:
Recommend us: