.. _api_examples:

# Worked examples

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

These examples assume you have already followed the :ref:`api_authentication`
instructions to generate an access token, and have :ref:`setup an environment variable <setup_RISKSCAPE_TOKEN>`
called `RISKSCAPE_TOKEN` that contains your token's secret, e.g.

```none
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 :ref:`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.

```none
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`:

```none
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
    :ref:`api_conventions`.

## More examples

- :ref:`api_upload_and_run` walks through uploading a file to a project,
  then running a model against it.
- :ref:`api_feeds` walks through using a feed token to access model run results from a feed.


<!-- TODO: Add further worked examples here, e.g. creating a project, checking a
scheduled run. Base each one on a real, run command and its real output,
following the pattern above. -->