boundary/website/content/docs/concepts/api-standards.mdx

---
layout: docs
page_title: API Standards
sidebar_title: API Standards
description: |-
  Boundary's API standards
---

# Overview

Boundary's HTTP API adheres to a set of standards that are rigidly followed. At its core, it is a standards-compliant JSON API for both input and output.

Before reading this page, it is useful to understand Boundary's [domain model](/docs/concetps/domain-model) to be aware of the terminology used here.

Boundary's API is also described via OpenAPI v2; the version corresponding to any tag of Boundary's source code can be found in Boundary's [GitHub repository](https://github.com/hashicorp/boundary/blob/main/internal/gen/controller.swagger.json).

Boundary's current API version is 1; all API paths begin with `/v1/`.

## Status Codes

* `2XX`: Boundary returns a code between `200` and `299` on success. Generally this is `200`, but implementations should be prepared to accept any `2XX` status code as indicating success. If a call returns a `2XX` code that is not `200`, it will follow well-understood semantics for those status codes.
* `400`: Boundary returns `400` when a command cannot be completed due to invalid user input, except for a properly-formatted identifier that does not map to an existing resource, which will return a `404` as discussed below.
* `401`: Boundary returns `401` if no authentication token is provided or if the provided token is invalid. A valid token that simply does not have permission for a resource will return a `403` instead. A token that is invalid or missing, but where the anonymous user (`u_anon`) is able to successfully perform the action, will not return a `401` but instead will return the result of the action.
* `403`: Boundary returns `403` if a provided token was valid but does not have the grants required to perform the requested action.
* `404`: Boundary returns `404` if a resource cannot be found. Note that this happens _prior_ to authentication/authorization checking in nearly all cases as the resource information (such as its scope, available actions, etc.) is a required part of that check. As a result, an action against a resource that does not exist will return a `404` instead of a `401` or `403`. While this could be considered an information leak, since IDs are randomly generated and this only discloses whether an ID is valid, it's tolerable.
* `405`: Boundary returns a `405` to indicate that the method is not implemented for the given resource.
* `500`: Boundary returns `500` if an error occurred that is not (directly) tied to invalid user input. If a `500` is generated, information about the error will be logged to Boundary's server log but is not generally provided to the client.

## Path Layout

Boundary follows a predictable path layout. There are two fundamental types of URL paths, each supporting a different set of operations.

### Collections

Collections of resources are top level paths with plural English names for the resource, e.g. `/roles` and `/hosts`. Collections support the following operations:

* Creation of new resources within that collection
* Listing of resources within that collection

All collection operations require supplying the enclosing resource. Depending on the collection type, this will be one of the following:

* A scope, indicating the scope in which an operation should take place. For instance, a POST to `/roles` would need to indicate whether the role should be created within the `global` scope or some organization scope like `o_1234567890`.
* A parent resource of the appropriate type. For instance, hosts and host sets are child resources of host catalogs. When creating a new host set within a host catalog, a POST to `/host-sets` would need to indicate the host catalog ID with which the host-set should be associated.

### Resources

Resources themselves are defined by ID specifiers within a collection path, e.g. `/roles/r_1234567890`. Resources support the following operations:

* Reading a resource's properties
* Updating a resource's properties
* Deleting a resource
* Custom methods specific to a resource type

Depending on the resource type, various parameters may be available. Some are common across all resource types (e.g. `name` and `description`); others are available only for specific types. Further, some concrete-types of abstract resources include an opaque `attributes` JSON object with type-specific values.

For instance, an authentication method is an abstract type; a `password` authentication method is a concrete implementation of that type. When creating such an auth method, a `type` parameter will indicate that it should be the `password` type, while values specific to the `password` type auth method, such as minimum password length, will be contained within an `attributes` object.

## Methods

The following method conventions are used within Boundary's API:

### GET

`GET` is used for reading a resource or listing resources in a collection. The behavior depends on whether the `GET` is issued against a collection (`/roles`) or a singular resource (`/roles/r_1234567890`). In the former case it lists resources within the collection; in the latter it performs a read on that particular resource.

### POST

`POST` is used for creating a resource or performing custom actions against a resoruce. When creating a resource, `POST` is used against a collection (`/roles`). When performing a custom action, `POST` is used against a particular resource (`/roles/r_1234567890:set-principals`).

### PATCH

`PATCH` is used to update a resource's parameters. The following are behaviors to be aware of when using `PATCH`:

* In nearly all cases, a `version` parameter is required. This is used for check-and-set, to ensure that the update operation is being performed against a known resource. The version parameter is returned from a `GET` operation on the resource so the current version, along with the resource's other current values, can be looked up at any time.
* Passing a JSON `null` for a parameter has the effect of reverting that parameter to its default. For some parameters (e.g. `name`) this will simply clear the value (as the default `name` for a resource is empty); for other parameters this will revert to the current defaults within Boundary.
* All parameters specified as part of a `PATCH` operation will be considered to be parameters that should be updated.

### DELETE

`DELETE` is used for deleting a specific resource, and is only used against a particular resource path.