API

This page describes the API endpoints currently implemented. Some might be missing, look in this folder for up to date information. (That's the source code, but it's pretty straight-forward.)

Table of Contents:

• Trees
  • Adding trees
  • Get tree details
  • List trees
  • Update tree properties
  • Update tree position
• Authentication
  • Login with Google

Adding trees

This endpoint is used to add one or more trees. Example request:

POST /v1/trees HTTP/1.0
Authorization: Bearer ..token..

{
  "points": [
    [1.2, 3.4],
  ],
  "species": "Fraxinus",
  "name": "Big Oak",
  "height": 25.0,
  "circumference": "3.72",
  "diameter": "15",
  "state": "healthy",
  "notes": null
}

Returns a list of added tree records with their ids. Example response:

200 OK HTTP/1.1
Content-Type: application/json

[
 {
  "id": 12345,
  "lat": 1.2,
  "lon": 3.4,
  "name": "Big Oak",
  "height": 25.0,
  "circumference": "3.72",
  "diameter": "15",
  "state": "healthy",
  "notes": null
 }
]

Get tree details

Example request:

GET /v1/trees/123 HTTP/1.0

Example response:

200 OK HTTP/1.0
Content-Type: application/json

{
  "lat": 1.2,
  "lon": 3.4,
  "name": "Big Oak",
  "height": 25.0,
  "circumference": "3.72",
  "diameter": "15",
  "state": "healthy",
}

List trees

Example request:

GET /v1/trees HTTP/1.0

Example response:

200 OK HTTP/1.1
Content-Type: application/json

{
  "trees": [
    {
      "id": 1,
      "lat": 37.7749,
      "lon": -122.4194
    },
    {
      "id": 2,
      "lat": 37.7749,
      "lon": -122.4194
    },
    {
      "id": 3,
      "lat": 37.7749,
      "lon": -122.4194
    }
  ]
}

Update tree properties

This call can change numeric properties, such as name, height, etc. For changing the location, a different endpoint should be used, see below.

Example request:

PUT /v1/trees/{id}
Content-Type: application/json

{
  "name": "Big Oak",
  "height": 27.0,
  "circumference": 1.4,
  "diameter": 17.0,
  "state": "sick",
}

Example response:

202 Accepted HTTP/1.1

Update tree position

Example request:

PUT /v1/trees/{id}/position
Content-Type: application/json

{
  "lat": 1.2,
  "lon": 3.4
}

Example response:

202 Accepted HTTP/1.1

Login with Google

This requires an access token received from Google. The token will be verified, user account will be created (if needed), then a local authentication token will be returned.

Example request:

POST /v1/login/google HTTP/1.1
Content-Type: application/json

{
  "token": "foobar"
}

Example response:

200 OK HTTP/1.1
Content-Type: application/json

{
  "token": "secret",
  "name": "Alice",
  "picture": "https://..."
}