Skip to content

API.md

Latest commit

 

History

History
894 lines (688 loc) · 33.4 KB

API.md

File metadata and controls

894 lines (688 loc) · 33.4 KB

API Docs

Auth

All endpoints require authentication. Authorization is supplied by sending an Authorization header in the form of Token <token>.

You can get a token by authenticating via OpenStreetMap.

Go to: https://host/auth/openstreetmap. You will be forwarded to the OpenStreetMap login page. After logging in successfully, you will be redirected to the frontend URL which will receive an authorization token from the backend.

If you need to use this token for automated scripts, export it from the frontend and setup your scripts to send it in an Authorization header as described above.

If you want to restrict your deployment to users of a trusted client app, you can wrap the JWT authentication token in another JWT token that is signed with a secret you share between the server and your trusted client app.

You will need to add that shared secret to the environment: JWT_TRUSTED_CLIENT_SECRET=your super-duper s3cret

Now on your trusted client, you will need to encode your tofix accessToken with the trustedClientSecret key.

const jwt = require('jwt-simple');

accessToken =  jwt.encode(accessToken, trustedClientSecret);

Schema validation

There are detailed rules around what we will and will not accept as part of Item FeatureCollections. These docs can be found at GEOJSON_SCHEMA.md

Endpoints

getQuadkeysQuery

Returns a promise for query for quadkey item counts

Parameters

  • projectId UUID project UUID
  • zoomLevel number zoom level to fetch aggregations for
  • within quadkey quadkey string to search within
  • q Object additional query / filter parameters

Returns Promise<Array> resolves to array of quadkey objects with counts

get-user

Get the user info.

Examples

curl https://host/v1/user

{
  id: 'testId',
  username: 'testUsername',
  image: 'https://gravatar.com/awesome/image'
}

get-status

Get the server status.

Examples

curl https://host

{
  status: 'OK'
}

get-quadkey-priority

Gets priority value for a quadkey+project. If quadkey does not exist, will return a priority of -1

Parameters

  • params Object Request URL parameters
    • params.quadkey string Quadkey to request priority for
  • query Object? Request URL query parameters
    • query.set_id string? Quadkey Set ID to get priority values for

Examples

curl https://host/v1/quadkeys/11002211
{ "priority": 0.777 }

get-projects

Get a list of projects.

Parameters

  • query Object? The request URL query parameters
    • query.name string? Name of project to filter by (optional)
    • query.is_archived (true | false)? default is false - set to true to return archived projects

Examples

curl https://host/v1/projects

[
  {
    id: '00000000-0000-0000-0000-000000000000',
    name: 'My Project',
    metadata: {},
    createdAt: '2017-10-18T00:00:00.000Z',
    updatedAt: '2017-10-18T00:00:00.000Z'
  }
]

get-project-tags

Get a list of project tags.

Parameters

  • params Object The request URL parameters
    • params.version string The API version
    • params.project string The project ID
  • query Object? The request URL query parameters
    • query.tag string? String to filter tag names by

Examples

curl https://host/v1/projects/00000000-0000-0000-0000-000000000000/tags

[
  {
    id: '22222222-2222-2222-2222-222222222222',
    project_id: '00000000-0000-0000-0000-000000000000',
    name: 'My Tag',
    metadata: {},
    createdAt: '2017-10-20T00:00:00.000Z',
    updatedAt: '2017-10-20T00:00:00.000Z'
  }
]

get-comments

Get a list of comments for an item

Parameters

  • params Object The request URL parameters
    • params.project string The project ID
    • params.item string The item ID

Examples

curl https://host/v1/projects/:project/items/:item/comments

[
  {
    "id": "e67c585d-d93f-4ea6-a59f-87b8b54e6efd",
    "createdBy": "usertwo",
    "body": "first",
    "coordinates": {
      "type": "Point",
      "coordinates": [
        0,
        0
      ]
    },
    "metadata": {},
    "createdAt": "2017-10-20T20:39:06.580Z",
    "updatedAt": "2017-10-20T20:39:06.580Z"
  },
  {
    "id": "3a47cd22-1761-4582-8cc6-32da1c0bd970",
    "createdBy": "userone",
    "body": "second",
    "coordinates": {
      "type": "Point",
      "coordinates": [
        0,
        0
      ]
    },
    "metadata": {},
    "createdAt": "2017-10-20T20:39:06.581Z",
    "updatedAt": "2017-10-20T20:39:06.581Z"
  }
]

get-items

Get a paginated list of items for a project.

Parameters

  • params Object The request URL parameters
    • params.project string The project ID
  • query Object? The request URL query parameters
    • query.lock ("locked" | "unlocked")? The item's lock status, must be 'locked' or 'unlocked'
    • query.page string The pagination start page (optional, default 0)
    • query.page_size string The page size (optional, default 100)
    • query.bbox string? BBOX to query by, string in W,S,E,N format (e.g. -1,-1,0,0)
    • query.status string? Status to filter items by
    • query.tags string? Comma-separated list of tag ids
    • query.from string? From date to filter by (must be a valid ISO 8601 date string)
    • query.to string? To date to filter by (must be a valid ISO 8601 date string)

Examples

curl https://host/v1/projects/:project/items

[
  {
    status: 'open',
    lockedTill: '2017-10-19T00:00:00.000Z',
    metadata: {},
    id: '405270',
    project_id: '00000000-0000-0000-0000-000000000000',
    pin: {
      type: 'Point',
      coordinates: [0, 0]
    },
    instructions: 'Fix this item',
    createdBy: 'user',
    updatedAt: '2017-10-19T00:00:00.000Z',
    createdAt: '2017-10-19T00:00:00.000Z',
    lockedBy: null
  }
]

get-project-stats

Get stats for a project

Examples

curl https://host/v1/projects/00000000-0000-0000-0000-000000000000/stats

{
  "total": 3,
  "tags": {
    "tag1": {
       "open": 1,
       "closed": 1
     },
     "tag2": {
       "open": 1
     }
  }

get-quadkeys

Returns a list of quadkeys with priority and item count data. The use-case is, for eg:

  • Give me data for all quadkeys at z8 within this z4 tile, with counts for items that have a status=open

Parameters

  • params Object URL parameters
    • params.project Object Project ID
  • query Object query parameters
    • query.within string? Quadkey to search within, defaults to the whole world
    • query.zoom_level integer? The zoom level you want results in (can be max 4 greater than zoom level of within quadkey param)
    • query.item_status string? item status to filter by for item counts
    • query.item_tags string? item tags (comma separated) to filter by for item counts
    • query.item_lock ("locked" | "unlocked")? The item's lock status, must be 'locked' or 'unlocked'
    • query.item_from string? From date of items, valid ISO8601 date string
    • query.item_to string? To date of items, valid ISO8601 date string

Examples

curl https://host/v1/quadkeys?within=0011&zoom_level=7&item_status=open
 [
   {
     quadkey: '0011000',
     item_count: 243,
     max_priority: 0.004
   },
   {
     quadkey: '00111001',
     item_count: 12,
     max_priority: 0.002
   },
   ...
 ]

Returns Array<Object> array of quadkey objects with the following keys:- quadkey: quadkey value at zoom_level requested

  • item_count: number of items within quadkey (after applying filters)
  • max_priority: max priority of constants.DEFAULT_ZOOM tile within aggregation

create-project-tag

Create a project tag.

Parameters

  • params Object The request URL parameters
    • params.version string The API version
    • params.project string The project ID
  • body Object The request payload
    • body.name string The tag name
    • body.metadata Object The tag metadata (optional, default {})

Examples

curl -X POST -H "Content-Type: application/json" -d '{"name":"My Tag"}' https://host/v1/projects/00000000-0000-0000-0000-000000000000/tags

{
  id: '33333333-3333-3333-3333-333333333333',
  metadata: {},
  name: 'My Tag',
  project_id: '00000000-0000-0000-0000-000000000000',
  updatedAt: '2017-10-20T00:00:00.000Z',
  createdAt: '2017-10-20T00:00:00.000Z'
}

create-comment

Create a comment

Parameters

  • params Object The request URL parameters
    • params.project string The project ID
    • params.item string The item ID
  • body Object The request body
    • body.body string Comment body
    • body.pin Array<number> Comment coordinates (optional, default null)
    • body.metadata Object Comment metadata (optional, default {})

Examples

curl -X POST -H "Content-Type: application/json" -d '{"body":"i like this item","pin":[0,0]}' https://host/v1/projects/00000000-0000-0000-0000-000000000000/items/77

{
  "id": "d0280f1f-c5cc-448d-9b88-5cf9e52f8e18",
  "createdBy": "userone",
  "body": "i like this item",
  "pin": {
    "type": "Point",
    "coordinates": [
      0,
      0
    ]
  },
  "metadata": {},
  "createdAt": "2017-10-23T17:18:01.801Z",
  "updatedAt": "2017-10-23T17:18:01.801Z"
}

catch

If there are items, return them. If there are not items, confirm that the project exists. If the project doesn't exist, return 404 Not Found. Otherwise, return empty array.

post-quadkey-priority

Write priority values for a quadkey (optionally tied to project) The backend will handle either INSERTing or UPDATEing as appropriate

Parameters

  • params Object Request URL parameters
    • params.quadkey string Quadkey to POST
  • body Object Request body
    • body.set_id string? Quadkey Set ID or null
    • body.priority float Priority value for Quadkey

get-project-tag

Get a project tag.

Parameters

  • params Object The request URL parameters
    • params.version string The API version
    • params.project string The project ID
    • params.tag string The tag ID

Examples

curl https://host/projects/00000000-0000-0000-0000-000000000000/tags/33333333-3333-3333-3333-333333333333

{
  id: '33333333-3333-3333-3333-333333333333',
  metadata: {},
  name: 'My Tag Tag',
  project_id: '00000000-0000-0000-0000-000000000000',
  updatedAt: '2017-10-20T00:00:00.000Z',
  createdAt: '2017-10-20T00:00:00.000Z'
}

create-project

Create a project.

Parameters

  • body Object The request body
    • body.name string The project name
    • body.quadkey_set_id string? Quadkey Set ID for this project
    • body.metadata Object The project metadata (optional, default {})

Examples

curl -X POST -H "Content-Type: application/json" -d '{"name":"My Project"}' https://host/v1/projects

{
  id: '00000000-0000-0000-0000-000000000000',
  metadata: {},
  name: 'My Project',
  updatedAt: '2017-10-19T00:00:00.000Z',
  createdAt: '2017-10-19T00:00:00.000Z'
}

create-item

Create an item in a project.

Parameters

  • params Object The request URL parameters
    • params.project string The project ID
  • body Object The request body
    • body.id string An identifier that can be used in future API requests for the item
    • body.instructions string Instructions on how to work on the item
    • body.pin [Lon, Lat] A 2D geometry point to represent the feature
    • body.lock ("unlocked" | "locked")? The item's lock status
    • body.status ("open" | "fixed" | "noterror")? The item's status
    • body.featureCollection FeatureCollection? The item's featureCollection context
    • body.metadata Object The item's metadata (optional, default {})

Examples

curl -X POST -H "Content-Type: application/json" -d '{"id":"405270","instructions":"Fix this item","pin":[0,0]}' https://host/v1/projects/00000000-0000-0000-0000-000000000000/items

{
  status: 'open',
  lockedTill: '2017-10-19T00:00:00.000Z',
  metadata: {},
  id: '405270',
  project_id: '00000000-0000-0000-0000-000000000000',
  pin: {
    type: 'Point',
    coordinates: [0, 0]
  },
  instructions: 'Fix this item',
  featureCollection: {
    type: 'FeatureCollection',
    features: []
  },
  createdBy: 'user',
  updatedAt: '2017-10-19T00:00:00.000Z',
  createdAt: '2017-10-19T00:00:00.000Z',
  lockedBy: null
}

update-project-tag

Update a project tag.

Parameters

  • params Object The request URL parameters
    • params.version string The API version
    • params.project string The project ID
    • params.tag string The tag ID
  • body Object The request payload
    • body.name string? The new tag name
    • body.metadata Object? The new tag metadata

Examples

curl -X PUT -H "Content-Type: application/json" -d '{"metadata":{"key":"value"}}' https://host/v1/projects/00000000-0000-0000-0000-000000000000/tags/33333333-3333-3333-3333-333333333333

{
  id: '33333333-3333-3333-3333-333333333333',
  metadata: {
    key: 'value'
  },
  name: 'My Tag',
  project_id: '00000000-0000-0000-0000-000000000000',
  updatedAt: '2017-10-20T01:00:00.000Z',
  createdAt: '2017-10-20T00:00:00.000Z'
}

get-project

Get a project.

Parameters

  • params Object The request URL parameters
    • params.project string The project ID

Examples

curl https://host/v1/projects/00000000-0000-0000-0000-000000000000

{
  id: '00000000-0000-0000-0000-000000000000',
  name: 'My Project',
  metadata: {},
  createdAt: '2017-10-18T00:00:00.000Z',
  updatedAt: '2017-10-18T00:00:00.000Z'
}

delete-comment

Delete a comment

Parameters

  • params Object The request URL parameters
    • params.project string The project ID
    • params.item string The item ID
    • params.comment string The comment ID

Examples

curl -X DELETE -H https://host/v1/projects/00000000-0000-0000-0000-000000000000/items/1234/comments/abcd-1234-abcd-1234

{
  "id": "1640ffd8-1d60-44a0-875c-d61231dbbdd5",
  "createdBy": "userone",
  "body": "second",
  "pin": {
    "type": "Point",
    "coordinates": [
      0,
      0
    ]
  },
  "metadata": {},
  "createdAt": "2017-10-23T17:13:25.585Z",
  "updatedAt": "2017-10-23T17:13:25.585Z"
}

update-project

Update a project.

Parameters

  • params Object The request URL parameters
    • params.project string The project ID
  • body Object The request body
    • body.name string? The project name
    • body.quadkey_set_id string? Quadkey Set ID for this project
    • body.metadata Object? The project metadata

Examples

curl -X PUT -H "Content-Type: application/json" -d '{"metadata":{"key":"value"}}' https://host/v1/projects/00000000-0000-0000-0000-000000000000

{
  id: '00000000-0000-0000-0000-000000000000',
  name: 'My Project',
  metadata: {
    key: "value"
  },
  createdAt: '2017-10-18T00:00:00.000Z',
  updatedAt: '2017-10-18T00:00:00.000Z'
}

delete-project-tag

Delete a project tag.

Parameters

  • params Object The request URL parameters
    • params.version string The API version
    • params.project string The project ID
    • params.tag string The tag ID

Examples

curl -X DELETE https://host/v1/projects/00000000-0000-0000-0000-000000000000/tags/11111111-1111-1111-1111-111111111111

{ message: 'Succesfully deleted tag 11111111-1111-1111-1111-111111111111' }

delete-project

Delete a project. Marks a project as "soft deleted"

Parameters

  • params Object Request URL params
    • params.project string Project ID

Examples

curl -X DELETE https://host/v1/projects/00000000-0000-0000-0000-000000000000
{"id": "00000000-0000-0000-0000-000000000000"}

get-item-tags

Get all tags for an item.

Parameters

  • params Object The request URL parameters
    • params.version string The API version
    • params.project string The project ID
    • params.item string The item ID

Examples

curl http://host/v1/projects/00000000-0000-0000-0000-000000000000/items/111111/tags

[
  {
    id: '22222222-2222-2222-2222-222222222222',
    project_id: '00000000-0000-0000-0000-000000000000',
    name: 'My Tag',
    metadata: {},
    createdAt: '2017-10-20T00:00:00.000Z',
    updatedAt: '2017-10-20T00:00:00.000Z',
    item_tag: {
      createdAt: '2017-10-20T00:00:00.000Z',
      updatedAt: '2017-10-20T00:00:00.000Z',
      itemAutoId: 1,
      tagId: '22222222-2222-2222-2222-222222222222'
    }
  }
]

get-item

Get an item for a project.

Parameters

  • params Object The request URL parameters
    • params.project string The project ID
    • params.item string The item ID

Examples

curl https://host/v1/projects/00000000-0000-0000-0000-000000000000/items/405270

{
  status: 'open',
  lockedTill: '2017-10-19T00:00:00.000Z',
  metadata: {},
  id: '405270',
  project_id: '00000000-0000-0000-0000-000000000000',
  pin: {
    type: 'Point',
    coordinates: [0,0]
  },
  instructions: 'Fix this item',
  featureCollection: {
    type: 'FeatureCollection',
    features: []
  },
  createdBy: 'user',
  updatedAt: '2017-10-19T00:00:00.000Z',
  createdAt: '2017-10-19T00:00:00.000Z',
  lockedBy: null
}

create-item-tag

Add a tag to an item.

Parameters

  • params Object The request URL parameters
    • params.version string The API version
    • params.project string The project ID
    • params.item string The item ID
  • body Object The request payload

Examples

curl -X POST -H "Content-Type: application/json" -d '{"tag":"22222222-2222-2222-2222-222222222222"}' https://host/v1/projects/00000000-0000-0000-0000-000000000000/items/111111/tags

[
  {
    id: '22222222-2222-2222-2222-222222222222',
    project_id: '00000000-0000-0000-0000-000000000000',
    name: 'My Tag',
    metadata: {},
    createdAt: '2017-10-20T00:00:00.000Z',
    updatedAt: '2017-10-20T00:00:00.000Z',
    item_tag: {
      createdAt: '2017-10-20T00:00:00.000Z',
      updatedAt: '2017-10-20T00:00:00.000Z',
      itemAutoId: 1,
      tagId: '22222222-2222-2222-2222-222222222222'
    }
  }
]

update-item

Update a project item.

Parameters

  • params Object The request URL parameters
    • params.project string The project ID
    • params.item string The item ID
  • body Object The request body
    • body.lock ("unlocked" | "locked")? The item's lock status
    • body.pin [Lon, Lat]? A 2D geometry point to represent the feature
    • body.status ("open" | "fixed" | "noterror")? The item's status
    • body.featureCollection FeatureCollection? The item's featureCollection context
    • body.instructions string? Instructions on how to work on the item
    • body.metadata Object? The item's metadata

Examples

curl -X PUT -H "Content-Type: application/json" -d '{"instructions":"Different instructions for fixing the item"}' https://host/v1/projects/00000000-0000-0000-0000-000000000000/items/405270

{
  status: 'open',
  lockedTill: '2017-10-19T00:00:00.000Z',
  metadata: {},
  id: '405270',
  project_id: '00000000-0000-0000-0000-000000000000',
  pin: {
    type: 'Point',
    coordinates: [0, 0]
  },
  instructions: 'Different instructions for fixing the item',
  featureCollection: {
    type: 'FeatureCollection',
    features: []
  },
  createdBy: 'user',
  updatedAt: '2017-10-19T00:00:00.000Z',
  createdAt: '2017-10-19T00:00:00.000Z',
  lockedBy: null
}

delete-item-tag

Remove a tag from an item.

Parameters

  • params Object The request URL parameters
    • params.version string The API version
    • params.project string The project ID
    • params.item string The item ID
    • params.tag string The tag ID

Examples

curl -X DELETE https://host/v1/projects/00000000-0000-0000-0000-000000000000/items/111111/tags/22222222-2222-2222-2222-222222222222

{
  id: '111111',
  project_id: '00000000-0000-0000-0000-000000000000',
  pin: { type: 'Point', coordinates: [77, 77] },
  instructions: 'Fix this item',
  createdBy: 'user',
  featureCollection: { type: 'FeatureCollection', features: [] },
  status: 'open',
  lockedBy: null,
  metadata: {},
  sort: 0,
  createdAt: '2017-10-20T00:00:00.000Z',
  updatedAt: '2017-10-20T00:00:00.000Z',
  lockedTill: '2017-10-20T00:00:00.000Z'
}

Returns Array<Object> tags - An array of remaining tags on the item

deleteItem

Delete an item. Sets the is_archived property to true

Parameters

  • req
  • res
  • next

Examples

curl -X DELETE https://host/v1/projects/00000000-0000-0000-0000000000/items/30
{"id": "30", "project": "00000000-0000-0000-0000000000"}

update-all-items

Updates an array of items. Note: max limit is 500

Parameters

  • params Object The request URL parameters
    • params.project string The project ID
  • body Array<Object> The request body
    • body.ids Array<String>? The item's unique iD
    • body.lock ("unlocked" | "locked")? The item's lock status
    • body.status ("open" | "fixed" | "noterror")? The item's status

Examples

curl -X PUT -H "Content-Type: application/json" -d '{lock: 'locked', ids: ["111111", "2222222"]}' https://host/v1/projects/00000000-0000-0000-0000-000000000000/items
[
  {
    status: 'open',
    lockedTill: '2017-10-19T00:00:00.000Z',
    metadata: {},
    id: '111111',
    project_id: '00000000-0000-0000-0000-000000000000',
    pin: {
      type: 'Point',
      coordinates: [0, 0]
    },
    instructions: 'Fix this item',
    createdBy: 'user',
    updatedAt: '2017-10-19T00:00:00.000Z',
    createdAt: '2017-10-19T00:00:00.000Z',
    lockedBy: 'you',
    lockedTill: '2017-10-19T00:15:00.000Z'
  },
  {
    status: 'open',
    lockedTill: '2017-10-19T00:00:00.000Z',
    metadata: {},
    id: '2222222',
    project_id: '00000000-0000-0000-0000-000000000000',
    pin: {
      type: 'Point',
      coordinates: [0, 0]
    },
    instructions: 'Fix this item',
    createdBy: 'user',
    updatedAt: '2017-10-19T00:00:00.000Z',
    createdAt: '2017-10-19T00:00:00.000Z',
    lockedBy: 'you',
    lockedTill: '2017-10-19T00:15:00.000Z'
  }
]