API documentation

Weekdone API is RESTful interface, providing access to the data in Weekdone system. The API supports JSON output.

Overview

Weekdone API is RESTful interface, providing access to most of the data in the system.The API accepts form-encoded content and query parameters in requests and all responses are encoded in JSON, including errors. UTF-8 is the only character encoding supported for both requests and responses.

Authentication

All API requests must contain way to authenticate the user and authorize access to requested data. Weekdone API supports OAuth 2.0 Authentication mechanism. A web application with a user’s authorization key, may access information and make changes to data stored in Weekdone as if it were that user.

OAuth 2.0

Weekdone API supports only Authorization Code Grant flow of the OAuth 2.0 framework. This is the most common strategy for traditional web applications and native desktop/mobile apps.

Registering your application

Before starting to implement the Weekdone API a new app must be registered with Weekdone to receive Client ID and Client Secret. This can be done from Applications page. All applications added by a client are visible to all admin level accounts of that client. As with all OAuth apps, you must supply an Application URL as well as a Redirect URL that successful (or failed) authentications will redirect to.

Requesting authorization from the user

Developers should use button with the text “Sign in with Weekdone” when redirecting users to Weekdone to start authorization flow.

To start the authorization flow users must be redirected to https://weekdone.com/oauth_authorize passing parameters in query string.

If either the client_id or redirect_uri do not match, the user will simply see a plain-text error. Otherwise, all errors will be sent back to the redirect_uri specified.

The user then sees a screen giving them the opportunity to accept or reject the request for authorization. In either case, the user will be redirected back to the redirect_uri.

Response back to application

User will be redirected back to redirect_uri with following parameters in the query string on successful authorization:

Token exchange

If user granted access to the application the code received by application must be exchanged for proper access token. The app must make POST request to https://weekdone.com/oauth_token passing following parameters in form-encoded post body:

Token exchange response

In the response, you will receive a JSON payload with the following parameters:

Requesting new access token with refresh token

access_token will expire in 60 minutes and new tokens must be requested using refresh_token. To request new access token the app must make POST request to https://weekdone.com/oauth_token passing following parameters in form-encoded post body:

Response will be the new access_token

Tips to get you started

There are several OAuth libraries to get you started

We have Zapier integration available if you are already using Zapier

Items

Items are what reports are made of. Each item may belong to one or several reports and evey item has following parameters:

Each report in Weekdone is identified by it’s number. The number is in form YYYYWW where YYYY is the year and WW is the week number.

{
  "status": "ok",
  "items": [
    {
      "id": 690,
      "inserted": "2013-03-28T13:37:54Z",
      "description": "item is here",
      "likecount": 0,
      "commentcount": 0,
      "type_id": 2,
      "team_id": 3,
      "user_id": 12,
      "priority": 1,
      "from_id": 144,
      "source": 0,
      "due_on": "2014-02-02"
    }
  ]
}

{
  "status": "ok",
  "likes": [
    {
      "id": 1360,
      "name": "John Doe"
    }
  ]
}

{
  "status": "ok",
  "comments": [
    {
      "id": 1360,
      "inserted": "2014-02-28T13:37:54Z",
      "comment": "this is item comment",
      "user_id": 12
    }
  ]
}

Report

Get weekly report data grouped by teams. See Items and Users for list of parameters

Each report in Weekdone is identified by it’s number. The number is in form YYYYWW where YYYY is the year and WW is the week number. Defaults to current week.

Teams

Each company account on Weekdone has one or move teams, which have following parameters:

Users

User object has following fields

Types

Reports are divided into types. When all teams in company use different templates, then team_id will be present. Types may have following fields:

Tags

Tags added to elements. Optional field “status”

Objectives

There are four level of Objectives: Company, Department, Team and Personal. All Objectives have almost same columns with following exceptions

• Department Objective has department_id
• Team Objective has team_id
• Personal Objective has team_id and user_id

“progress” field of Objectives is calculated based on Key Results “progress” and therefore cannot be updated directly.

Key Results

{
  "status": "ok",
  "data": [
    {
      "id": 1,
      "description": "Reach the goal"
      "type": "company",
      "progress": 60,
      "results": [
        {
          "id": 1,
          "result": "Do important things 5 times",
          "type": "times",
          "weight": 1,
          "progress": 3,
          "startval": 0,
          "maxval": 5,
          "commentcount": 0,
          "comments": []
        }
      ]
    }
  ]
}

Company details

Each company has several configuration settings:

Responses