Worksection
Clients API (v.01)
Basic principles
1. You can access API using http _GET or _POST request
where your-domain.com - is your account address in Worksection.
Your request must contain the following parameters:
action – operation
page – path to the project, task or subtask in the system without account address. Example: /project/12345/
hash –security hash MD5, that contaions 3 parameters page, action, apikey.
Account owner can get Apikeyhere
PHP example of generating security hash : $hash =md5($page.$action.$apikey).
Text data shall be transmitted in UTF-8 unicode
2. Response is coded inJSON, UTF-8
“Status” field contains the status of the query:
ok – successful request.
error – something goes wrong
In case when status is not “ok” for the “status_code” field and “message” filed contains error information (in some cases, additional field “message_details” with the details of an error will be transmitted). Here us status_code/message details:
// Errors with request or hash
0 - Action is invalid
1 - Action is required
2 - Action hash is missed or invalid
// Errors with path
4 - Project is invalid
5 - Task is invalid
6 - Subtask is invalid
3 - Page is invalid
7 - Project is required
8 - Task is required
9 - Subtask is required
// Other errors
10 - Field is required, message_detailscontains field name
11 - Invalid email, message_detailscontains invalid email
12 - Task is already closed
13 - Task has children
14 - Subtask is already closed
15 - Subtask has children
An example of a response in case of success
{
"status": "ok"
}
An example of a response in case of an error
{
"status": "error",
"status_code": 2,
"message": "Action hash is missed or invalid"
}
API function– getting Projects/Tasks
Getting a list of projects (get_projects)
Returns titles of all projects, their statuses (archive, active, pending), company and a relative link to each project
There is no need to pass pagein this request
An example of JSON response
{
“status”: “ok”,
“data”: [
{
“name”: “PROJECT_NAME”,
“page”: “/project/PROJECT_ID/”,
“status”: “archive”,
“company”: “COMPANY_NAME”
},
{
“name”: “PROJECT_NAME”,
“page”: “/project/PROJECT_ID/”,
“status”: “active”,
“company”: “COMPANY_NAME”
}
]
}
Getting account tasks priorities (get_priority)
Returns active tasks titles, their priorities and a relative link to the task
“user_from” and “user_name” fields contains information about an author of the task and a responsible employee
Data fields:
date_added - creation time and date
date_start – task start date (if set)
date_end – task end date (if set)
An example of JSON response
{
"status": "ok",
"data": [
{
"name": "TITLE",
"page": "/project/PROJECT_ID/TASK_ID/",
"priority": "0..10",
"user_from": {
"email": "USER_EMAIL",
"name": "USER_NAME"
},
"user_to": {
"email": "USER_EMAIL",
"name": "USER_NAME"
},
"date_added": "YYYY-MM-DD HH:II",
"date_start": "YYYY-MM-DD",
"date_end": "YYYY-MM-DD",
}
]
}
Getting a tree of tasks and subtasks of the project (get_tasks)
Returns tasks titles, tasks statuses (active, done), their priorities и a relative link to each task.
“user_from” and “user_name” fields contains information about an author of the task and a responsible employee
Data fields:
date_added - time and date of creation of the task
date_closed – time and date of closing of the task
date_start – установленная start date of the task (if set)
date_end – установленная finish date of the task (if set)
“Child” filed (if exist) will contain a list of subtasks in the same format. Available 2 level of nested subtasks : tasks/ sub-tasks/ sub-sub-tasks.
An example of JSON response
{
"status": "ok",
"data": [
{
"name": "TITLE",
"page": "/project/PROJECT_ID/TASK_ID/",
"status": "done",
"priority": "0..10",
"user_from": {
"email": "USER_EMAIL",
"name": "USER_NAME"
},
"user_to": {
"email": "USER_EMAIL",
"name": "USER_NAME"
},
"date_added": "YYYY-MM-DD HH:II",
"date_start": "YYYY-MM-DD",
"date_end": "YYYY-MM-DD",
"date_closed": "YYYY-MM-DD HH:II",
"child": [
{
"name": "SUBTASK_NAME",
"page": "/project/PROJECT_ID/TASK_ID/SUBTASK_ID/",
"status": "done",
"priority": "0..10",
"user_from": {
"email": "USER_EMAIL",
"name": "USER_NAME"
},
"user_to": {
"email": "USER_EMAIL",
"name": "USER_NAME"
},
"date_added": "YYYY-MM-DD HH:II",
"date_start": "YYYY-MM-DD",
"date_end": "YYYY-MM-DD",
"date_closed": "YYYY-MM-DD HH:II"
}
]
},
{
"name": "TASK_NAME",
"page": "/project/PROJECT_ID/TASK_ID/",
"status": "done",
"user_from": {
"email": "USER_EMAIL",
"name": "USER_NAME"
},
"user_to": {
"email": "USER_EMAIL",
"name": "USER_NAME"
},
"date_added": "YYYY-MM-DD HH:II",
"date_closed": "YYYY-MM-DD HH:II"
}
]
}
API: functions – Posting tasks&comments
Posting comments on a task or subtask (post_comment)
Fieldpagemust fitto task/subtask url
Required parameters:
email_user_from – email of the author of the comment
text – text of the comment
Optional parameters:
hidden – the list of the emails of the users to whom this comment will be allowed. It will be hidden for other users. Ifhiddenis not passed – then task will be public.
If response is success it contains status “ok” and URL on posted comment
{
"status": "ok",
"url": "
}
Task creation (post_task)
Fieldpagemust fitto project url
Required parameters:
email_user_from – email of the author of the task
email_user_to – email of the responsible for the task
title – task’s title
Optional parameters:
text – text of the comment
priority – priority, number from 0 to 10
datestart – start date of the task (DD.MM.YYYY)
dateend – finish date of the task (DD.MM.YYYY)
subscribe – listofpeople's emails, you want to subscribe
hidden – listofpeople's emails, you want to allow access to this task. Task will be hidden from others teammates. Ifhiddenis not passed – then task will be public.
If response is success it contains status “ok” and URL on posted task
{
"status": "ok",
"url": " "
}
SubTask creation (post_subtask)
Fieldpagemustfittoparenttaskurl, thatwillcontainthissubtask
Required parameters:
email_user_from – email of the author of the task
email_user_to – email of the responsible for the task
title – task’s title
Optional parameters:
text – text of the comment
priority – priority, number from 0 to 10
datestart – start date of the task (DD.MM.YYYY)
dateend– finish date of the task (DD.MM.YYYY)
hidden – listofpeople's emails, you want to allow access to this subtask. SubTask will be hidden from others teammates. Ifhiddenis not passed – then task will be public.
If response is success it contains status “ok” and URL on posted subtask
{
"status": "ok",
"url": "
}
API: Functions — managing task and subtasks
Close task (close_task)
Marktaskasdone for thispage. The task must be opened and do not contain opened subtasks
Close subtask (close_subtask)
Marksubstaskasdone for this page. The task must be opened and do not contain opened subtasks
Subscribe user (subscribe)
The field email_user must contain an email of the user, who will be subscribed on the task page
Unsubscribe user (unsubscribe)
The field email_user must contain an email of the user, who will be unsubscribed from the task page
API: functions – attaching files to tasks/subtasks/comments
YouneedtogeneratePOSTrequest (multipart/form-data)
Every field name fit to a single file: attach[]
How to send files to POST request you can read here:
Example:
POST HTTP/1.0\r\n
Host: your-domain.com\r\n
Content-Type: multipart/form-data; boundary=1BEF0A57BE110FD467A\r\n
\r\n
--1BEF0A57BE110FD467A\r\n
Content-Disposition: form-data; name="action"\r\n
\r\n
post_comment\r\n
--1BEF0A57BE110FD467A\r\n
Content-Disposition: form-data; name="attach[]"; filename="filename.txt"\r\n
Content-Type: application/octet-stream\r\n
Content-Transfer-Encoding: binary\r\n
\r\n
Содержимоефайла filename.txt\r\n
--1BEF0A57BE110FD467A--\r\n