API conventions

This page covers the general rules that apply across the RiskScape Platform API. 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.

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