Using the API
Users may also inspect the code and console output from the above apps to see how the API is used in practice.
Note
Most resources require a JWT token with every request; for more on this, see Authentication.
The included Insomnia collection makes use of Environment
s, which allow for the provision of arbitrary variables that can be used anywhere in the app. The prod
environment, for example, defines api_url
as https://api.datamermaid.org/v1
. In this way users can easily switch between testing in different environments (including local
).
Before you can start using the Insomnia collection, you need to:
Have or create a MERMAID user account appropriate to the targeted environment, easily obtainable by going to https://collect.datamermaid.org/ (production).
Change the
project
environment variable to the id of a project in MERMAID to which you belong, by copying/pasting from the Collect url, like this:
Formats
All responses to GET requests for non-aggregated-view urls are returned as standard JSON, with
content-type
= application/json
. In addition, Aggregated views offer two additional formats, accessible by
appending the relevant string to resources:
.../csv/
: returns comma-separated 2D matrix (some fields are JSON).../geojson/
: returns GeoJSON
GET
requests will return lists of objects. Appending an object id to most resources will return a single object.
Pagination
All JSON and GeoJSON responses to GET requests are paginated with a default page_size
of 100 that may be increased to a maximum of 5000 by appending a limit
query parameter. Results contain count
, next
, and previous
in addition to a list of actual results
, e.g.::
{
"count": 3275,
"next": "https://api.datamermaid.org/v1/fishspecies/?page=2",
"previous": null,
"results": [...]
}
Filters
fishspecies
support filtering by fields available from that resource, e.g.https://api.datamermaid.org/v1/fishspecies/?genus=f5263c54-ea12-4a18-8200-d52967376d1a
https://api.datamermaid.org/v1/fishspecies/?ordering=genus__name
https://api.datamermaid.org/v1/fishspecies/?search=Abalistes
https://api.datamermaid.org/v1/projects/8c213ce8-7973-47a5-9359-3a0ef12ed201/beltfishes/sampleunits/?site_name=KOE01,Lhok%20Weng