.. _api_conventions:

# API conventions

This page covers the general rules that apply across the RiskScape
:ref:`Platform API <api_overview>`. These conventions may help advanced users
build external applications or dashboards that interact with the Platform.

The API is RESTful. The `/api` URL identifies the resource that it's acting on,
for example, `/api/projects` would deal with 'project' resources. You can use
the usual HTTP methods to interact with a resource:
- `GET` to read a resource
- `POST` to create a resource
- `PUT` to update a resource
- `DELETE` to remove a resource

## Data format

By default, the API returns JSON.
If you browse to an API URL in a web browser, you will see an HTML page
describing the same data instead, because your browser asks for HTML.

If you are calling the API from a script or another program, rather than
browsing it yourself, set the `Accept` header on your request to
`application/json` to make sure you get JSON back.

## Requests that change data

For requests that create or update data (`POST`, `PUT`), send a JSON body and
set the `Content-Type` header to `application/json`.

## Links between resources

Responses link to related resources rather than nesting all the related data
in one response.
For example, a project response links to its files and members, rather
than including them directly.
Follow these links to get more detail about the related resources.

.. note::
    When you are exploring the API in your web browser, these links appear as ordinary
    clickable links on the page.

## Indexes

Resources that represent a list of things, e.g. `/api/projects`, are called
*index* resources. They return a collection of links to the individual
items, rather than the items themselves.

## Errors

If a request fails, the API returns an HTTP status code that describes the
problem, along with a JSON body with more detail. For example:

- `400`: the request was malformed, e.g. missing a required field.
- `401`: you are not authenticated.
See :ref:`api_authentication`.
- `403`: you are authenticated, but not allowed to do this.
- `404`: the resource does not exist, or you cannot see it.

## IDs

Most resources are identified by a numeric ID that appears in the URL, e.g.
`/api/projects/by-id/123`. IDs are assigned by the server and are not reused.
You may need to browse the API to work out the ID for a resource.

## Slugs

If you don't know a project ID, you can look up a project by name. This requires using the project slug,
which is in the format `ORGANIZATION/GROUP/PROJECT`.
When you use the regular RiskScape Platform web interface, the project slug
appears in the URL when you view a project. So for example, the getting-started project uses the following:
- Platform web interface link: https://riskscape.nz/projects/riskscape/example/getting-started/models
- Slug: `riskscape/example/getting-started`
- API link: https://riskscape.nz/api/projects/by-full-slug/riskscape/example/getting-started