API

/!\ work in progress.

This page describes the API for the Tasking Manager.

General Information

This API is based on the ideas of the RESTful API.

Projects

List of projects

GET /projects.json

Returns the list of projects.

Response: Status code: 200

[{
    "id": 53,
    "name": "Name of the project",
    "short_description": "Short description",
    "created": "2014-10-06 13:06:05.130285Z",
    "author_id": 2159
}, {
    ...
}]

Notes:

• Private projects will not appear in this list.
• The result is paginated (100 items per page)

Details for a project

GET /project/{project_id}.json

Return the properties for a project for the given project_id.

Response: Status code: 200

{
    "geometry": {
        "type": "MultiPolygon",
        "coordinates": [
            [
                [
                    [[[[-10.716800237592842, 6.249249636476994], [-10.716388083559112, 6.251156960592158], [...], [-10.716800237592842, 6.249249636476994]]]]
                ]
            ]
        ]
    },
    "type": "Feature",
    "id": 53,
    "properties": {
        "name": "The project name",
        "description": "The description"
    }
}

Tasks

List of tasks with state and lock status

GET /project/{project_id}/tasks.json

Returns the list of tasks for a project.

Response: Status code 200

{
    "type": "FeatureCollection",
    "features": [{
        "geometry": {
            "type": "MultiPolygon",
            "coordinates": [
                [
                    [
                        [-1.4639282223940357, 12.35878304481958],
                        [-1.4611816403632567, 12.35878304481958],
                        [-1.4611816403632567, 12.361465965167433],
                        [-1.4639282223940357, 12.361465965167433],
                        [-1.4639282223940357, 12.35878304481958]
                    ]
                ]
            ]
        },
        "type": "Feature",
        "id": 53,
        "properties": {
            "y": 70071,
            "x": 65003,
            "state": 0,
            "locked": null,
            "zoom": 17
        }
    }, {
        [...]
    }]
}

Notes:

• x, y and zoom: the position of the task is in a mercator grid. May not be available if the task is an arbitrary polygon.
• state: the current state of the task.
• 0: ready, not worked on yet,
• 1: invalidated,
• 2: done,
• 3: validated,
• -1: removed.
• locked: tells whether the task is currently locked or not.

Task details (not implemented yet)

GET /project/{project_id}/task/{task_id}.json

Returns the details informations about a task.

Response: Status code 200

{
    "geometry": {
        "type": "MultiPolygon",
        "coordinates": [
            [
                [
                    [-1.4639282223940357, 12.35878304481958],
                    [-1.4611816403632567, 12.35878304481958],
                    [-1.4611816403632567, 12.361465965167433],
                    [-1.4639282223940357, 12.361465965167433],
                    [-1.4639282223940357, 12.35878304481958]
                ]
            ]
        ]
    },
    "type": "Feature",
    "id": 53,
    "properties": {
        "y": 70071,
        "x": 65003,
        "state": 0,
        "locked": null,
        "zoom": 17
    }
}

Validate (not implemented yet)

PUT /project/{project_id}/task/{task_id}/state

Request body:

{
    "state": 3,
    "comment": "A comment"
}

Response:

{
    "msg": "Task validated"
}

Note:

The task MUST be locked.

The comment is optional.

Invalidate (not implemented yet)

PUT /project/{project_id}/task/{task_id}/state

Request body:

{
    "state": 1,
    "comment": "A comment"
}

Response: Status code 200

{
    "msg": "Task invalidated"
}

Note:

The task MUST be locked.

The comment is mandatory.

Lock (not implemented yet)

POST /project/{project_id}/task/{task_id}/lock

Locks the given task. Required prior to mark as done or validate. Other contributors will not be able to change the task state if task is locked.

A task may be automatically unlocked after a given amount of time (2 hours).

Response: Status code 200

{
    "msg": "Task locked"
}

Unlock (not implemented yet)

DELETE /project/{project_id}/task/{task_id}/lock

Unlocks the given task.

Response: Status code 200

{
    "msg": "Task unlocked"
}

Create a task (XYZ) (not implemented yet)

POST /project/{project_id}/task

Creates a new task in the given project for a position in the mercator grid.

Request body:

{
    "x": 152,
    "y": 524,
    "z": 9
}

• x, y, z: The position (column, row, and zoom) in the web mercator grid. Only valid if the project is in a "grid mode".

Response: Status code 200

{
    "msg": "Task created",
    "task": {
        "id": 24
    }
}

Note:

A task can also be created using a geometry. See below.

Create a task (Geometry) (not implemented yet)

POST /project/{project_id}/task

Creates a new task in the given project using a GeoJSON geometry.

Request body:

{
    "type": "MultiPolygon",
    "coordinates": [
        [
           [
                [[[[-10.716800237592842, 6.249249636476994], [-10.716388083559112, 6.251156960592158], [...], [-10.716800237592842, 6.249249636476994]]]]
            ]
        ]
    ]
}

Response: Status code 200

{
    "msg": "Task created",
    "task": {
        "id": 24
    }
}

Note:

The geometry must be a polygon or multipolygon.

A task can also be created using a position in the mercator grid. See above.