Skip to content

API Endpoints

Jump to bottom
jalal (Tim Pushman) edited this page Apr 9, 2019 · 9 revisions

Triffids Server API

Add and modify this document as we add and change endpoints.

See Data Spec for the data returned.

Endpoints (based on /api/v1)

  • GET /parks -- return a list of all parks
  • GET /parks/{pcode} -- find details of the park identified by pcode
  • GET /parks/loc?lat=0.000&lng=0.000&radius=100 -- return the nearest parks to this point in a specified radius (in metres)
  • GET /parks/info/{pcode} -- return the info page for the park
  • GET /trees/{pcode} -- show trees in this park
  • GET /trees/{pcode}?latincode={latin_code} -- show trees in this park of this species
  • GET /trees?id=treeid -- show tree with this record ID (e.g. recordid=ec86bf43c7da17c479f9252e6bbcc8d6ef544a00)
  • GET /trees/loc?lat=0.000&lng=0.000&radius=100 -- show trees at this location in a specified radius (in metres)
  • GET /benches/loc?lat=0.000&lng=0.000&radius=100 -- show benches at this location in a specified radius (in metres). Note: OpenBenches returns a maximum of 20 results for each request

HTTP Response codes

  • 200 -- All ok
  • 400 -- Bad syntax in Request
  • 404 -- Not found, invalid route
  • 429 -- Maximum reached (Too many API requests)
  • 500 -- Server fell over

Notes

  • pcode refers to the park code, or site_code, normally 6 characters, sometimes digits.
  • We could also represent the location as lat,lng to give an endpoint like: /api/v1/trees/51.2345,-2.123412 but I find that less clear

The normal way to describe an endpoint is: verb url noun modifiers and the noun is always the plural

So GET https://api.triffids.org/api/v1/parks parks is the noun. And GET https://api.triffids.org/api/v1/trees?lat=0.000&lng=0.000 lat and lng are the modifiers.

With /api/v1/parks/{pcode} the pcode is the default modifier and becomes part of the URL, the singular version of the endpoint. Similarly with /api/v1/trees/{pcode}

Clone this wiki locally