Worked examples

This page collects short, complete examples of common tasks using the API.

These examples assume you have already followed the Authentication instructions to generate an access token, and have setup an environment variable called RISKSCAPE_TOKEN that contains your token’s secret, e.g.

read -sr -p "Access token: " RISKSCAPE_TOKEN

The examples use curl, but the same requests will work from any HTTP client or scripting language. See also API conventions for general conventions that the RiskScape Platform API uses.

Checking the API is up

The /api/ping API provides a simple way to sanity-check that you can access the RiskScape Platform, e.g.

curl -s -u TOKEN:$RISKSCAPE_TOKEN https://riskscape.nz/api/ping

In a successful case, the ping API simply returns pong.

Tip

If /api/ping doesn’t work, it may highlight a problem with your credentials (e.g. your access token has expired) or some other issue, like a networking connectivity problem.

Looking up a project

RiskScape Platform project URLs in the browser are made up of an organization, group and project name, e.g. riskscape/example/getting-started. You can look a project up the same way through the API, using /projects/by-full-slug:

curl -s -u TOKEN:$RISKSCAPE_TOKEN \
  https://riskscape.nz/api/projects/by-full-slug/riskscape/example/getting-started

This will return the details for the getting-started project, in JSON.

Tip

A browser sends an Accept header that asks for HTML, so opening this same URL in your browser shows a readable page instead of raw JSON. See API conventions.

More examples