# Signal K REST API Conventions

## Overview

This document outlines the conventions used when defining Signal K REST APIs.

- Managing Configuration
- Multiple Devices
- Multiple Providers

### Managing Configuration

APIs that provide configuration operations should provide operations under the `_config` path parameter.

Example: Set apiOnly mode in Course API

    HTTP POST "/signalk/v2/api/vessels/self/course/_config/apiOnly"

Example: Clear apiOnly mode in Course API

    HTTP DELETE "/signalk/v2/api/vessels/self/course/_config/apiOnly"

### Multiple Devices

When an API supports the installation of multiple devices (e.g. autopilots, radars, etc) it can designate one device to receive commands if a specific device / provider is not targeted.

This done by using the `_default` parameter in the request path in place of the device identifier.

Example: Engage the default autopilot

    HTTP POST "/signalk/v2/api/vessels/self/steering/autopilots/_default/engage"

Example: Engage a specific autopilot

    HTTP POST "/signalk/v2/api/vessels/self/steering/autopilots/raymarine-n2k/engage"

Example: Retrieve the status of the default autopilot

    HTTP GET "/signalk/v2/api/vessels/self/steering/autopilots/_default"

Example: Retrieve the status of a specific autopilot

    HTTP GET "/signalk/v2/api/vessels/self/steering/autopilots/raymarine-n2k"

### Multiple Providers

Some APIs support the use of one or more providers to provide:

- An aggregated set of data from varied sources (e.g. resources)
- The ability to interact with one or more services (e.g. Weather providers)

In these scenarios it is often required to perform operations to manage or target a provider.

Provider specific operations can use either the:

- `_providers` path parameter
- `provider` query parameter.

Example: Retrieve the default provider servicing charts resources

    HTTP GET "/signalk/v2/api/resources/charts/_providers/_default"

Example: Set the provider to handle creating new chart sources.

    HTTP POST "/signalk/v2/api/resources/charts/_providers/_default/my-chart-plugin"

Example: Create a new waypoint using the specified provider.

    HTTP POST "/signalk/v2/api/resources/waypoints?provider=my-plugin-id"