My favorites ▼ | Sign in
Project Home Wiki Issues
Search
for
APIDocumentation  
Updated Mar 8, 2012 by thomas.b...@gmail.com

Table of Content

Introduction

Producteev exposes some of its functionality via an Application Programming Interface (API). This document is a reference for that functionality, and aims to serve as a reference for developers building tools that connect to Producteev.

API Authentication

Get a developer API KEY

To use the API please request an API Key at http://www.producteev.com/developers.php. We will send you back an API KEY and API SECRET by email.

Signature

For all API requests, you will need to submit your api key and create a signature.

Example: 

https://api.producteev.com/tasks/set_responsible.json?id_task=14159&id_responsible=26535token=49d17774aa58d16f2c207aba8a670814&api_key=your_api_key&api_sig=your_signature

your_api_key should be replaced with your application's API key.`

your_signature is a signature of all the parameters sent to the call. Signatures are created by concatenating every scalar argument (ie: non array) listed in alphabetical order with your api secret:

Assuming your API key is 9876543210 and your secret is 000123456, your signature string would be: 

api_key9876543210id_responsible26535id_task14159token49d17774aa58d16f2c207aba8a670814000123456

Get the md5 of the signature string and that is the api_sig parameter: 

43428098421a7f23e49880b3d3fd397e

Now we can build the full request URL: 

https://api.producteev.com/tasks/set_responsible.json?id_task=14159&id_responsible=26535&token=49d17774aa58d16f2c207aba8a670814&api_key=11111&api_sig=49e89cc29f26dad5239848495baebd92

Here an example of code that will help you to create the signature:

PHP: 

/*
   * Generate a signature using the application secret key.
   *
   * @param $params_array   an array of parameters,
   *                        NOT INCLUDING the signature itself
   * @param $secret         your app's secret key
   *
   * @return a hash of the signature
   */
  public static function generate_signature($params_array, $secret) {
    $str = '';                                                                                                                                                      
        //Note: make sure that the signature parameter is not already included in $params_array
    ksort($params_array);                                                                                                                                           
    foreach ($params_array as $k=>$v) {
                if(is_scalar($v)) {
                        $str .= "$k$v";                                                                                                                             
                }
    }
    $str .= $secret;                                                                                                                                                
    return md5($str);                                                                                                                                               
  }

Objective-C: 

- (NSString*) generateSignature:(NSDictionary*)params {

        NSMutableString* sig = [NSMutableString string];                                                                                                            
        NSArray* keys = [params.allKeys sortedArrayUsingSelector:@selector(caseInsensitiveCompare:)];                                                               
        for (id key in [keys objectEnumerator]) {
                id value = [params valueForKey:key];                                                                                                                
                if ([value isKindOfClass:[NSString class]]) {
                        [sig appendString:key];                                                                                                                     
                        [sig appendString:value];                                                                                                                   
                }
        }
        [sig appendString:yourApiSecret];                                                                                                                           
        return [sig md5Hash];                                                                                                                                       
}

User Login

Most Producteev API methods require user to be logged in. All responses are relative to the context of the logged-in user. For example, an attempt to retrieve information about a task who does not belong to the requesting user team will fail.

Request a token

To authenticate an user, use the following method: users/login.format. This call will return you a token you should provide as a parameter in every following call to Producteev API.

Example: 

https://api.producteev.com/tasks/view.json?api_key=11111&api_sig=49e89cc29f26dad5239848495baebd92&id_task=83697&token=49d17774aa58d16f2c207aba8a670814

HTTPS / SSL

All Producteev API methods should be accessed using SSL connection.

Response format

You can simply change the file extension of any request to get results in the format of your choice. Producteev currently supports the following data formats: JSON and XML format.

Parameters

API methods take optional or required parameters. See Wiki page to have details about methods and their arguments. Remember to convert to UTF-8 and URL encode parameters that take complex strings.

HTTP Status Codes

The Producteev API attempts to return appropriate HTTP status codes for every request. Here is the various status codes:

  • 200 OK: request is OK.
  • 401 Not Authorized: either you need to provide authentication token, or the authentication credentials provided are not valid.
  • 403 Forbidden: we understand your request, but we refuse to fulfill it. An additional error message should explain why.
  • 404 Not Found: either you're requesting an invalid URI or the resource in question doesn't exist (ex: no such methods for instance).
  • 500 Internal Server Error: We did something wrong. We are probably already working on it but please let us know so we can check it out.
  • 503 Service Unavailable: Probably overloaded at the time. Try again later.

When the Producteev API returns error messages, it does so in your requested format. For example, an error from an JSON request might look like this: 

{
      error: {
          request: "/api/dashboards/view.json?id_dashboard=1337"
          message: "Access denied to the dashboard"
      }
}

Date and time

Valid date formats are PHP supported date and time formats (see http://us.php.net/manual/en/datetime.formats.php for more details) Every date sent as parameters should be based on the Producteev server time.

You can request server time using the following methods: 

https://api.producteev.com/time.format

Expected response: 

{
        time: {
                value: Fri, 11 Jun 2010 17:49:27 -0400
        }
}

Encoding

The Producteev API supports UTF-8 encoding. Every parameter string sent to the API should be URL encoded.

Examples

Authenticate an user

Request: 

https://api.producteev.com/users/login.json?email=john@producteev.com&password=xxxxxx&api_key=11111&api_sig=49e89cc29f26dad5239848495baebd92

Response: 

{
        login: {
                token: 0acf9b20f121212cba39056b1836e72
                email: john@producteev.com
        }
}

Get current user information

Request: 

https://api.producteev.com/users/view.json?api_key=11111&api_sig=49e89cc29f26dad5239848495baebd92

Response: 

{r: [ ]
          facebook_id: "0"
      }
}

Get workspace information

Request: 

https://api.producteev.com/dashboards/view.json?id_dashboard=1&api_key=11111&api_sig=49e89cc29f26dad5239848495baebd92

Response: 

{
dashboard: {
        id_dashboard: 1
        id_creator: 2
        title: My Super Workspace
        write_ok: 0
        time_lastchange: Thu, 10 Jun 2010 15:55:30 -0400
        status: 1
        deleted: 0
        accesslist: [
                {
                        user: {
                                id_user: 2
                                firstname: John
                                lastname: Lagend
                                company: Producteev
                                email: john@producteev.com
                                timezone: US/Eastern
                                time_signup: Fri, 02 Apr 2010 10:29:34 -0400
                                lang: en
                                avatar: https://api.producteev.com/users/pictures/00002-111111111.jpg
                                deleted: 0
                                default_dashboard: 1
                                colleagues: [ ]
                                facebook_id:
                                dashboard_status: 1
                        }
                }
                {
                        user: {
                                id_user: 13
                                firstname: Elie
                                lastname: Copter
                                company: Producteev
                                email: ec@producteev.com
                                timezone: US/Eastern
                                time_signup: Fri, 02 Apr 2010 10:29:39 -0400
                                lang: en
                                avatar: https://api.producteev.com/users/pictures/00013-66666666.jpg
                                deleted: 0
                                default_dashboard: 1
                                colleagues: [ ]
                                facebook_id:
                                dashboard_status: 1
                        }
                }
                ]
        }
}

Delete a task

Request: 

https://api.producteev.com/tasks/delete.json?id_task=1337&api_key=11111&api_sig=49e89cc29f26dad5239848495baebd92

Response: 

{
        stats: {
                result: TRUE
        }
}

How do I report bugs and issues with the Producteev API?

Use the Issue Tracking tab or shoot us a message in our discussion group.

Methods descriptions

Your will find the liist of every API calls and their parameters on this Wiki page.


► Sign in to add a comment
Powered by Google Project Hosting