The Piiano Vault REST API allows you to access and manage collections, objects, tokens, users, policies and other resources within the Piiano Vault in a simple, programmatic way using conventional HTTP requests and standard HTTP response codes
The API follows RESTful conventions when possible, with most operations performed by
DELETE requests. Request and response bodies are JSON-encoded.
Using this API reference, you'll find details for each endpoint and type of resource used in the API.
You can also try each API endpoint using Send API request.
The Piiano Vault API is versioned and the version is part of the API base URL. The current version is
1.0 so the URL will be prefixed with
A new API version is released when we introduce a backwards-incompatible change to the API. For new features and additions to the API, such as adding a new API endpoint, or including a new object in an existing API endpoint's response, there won't be a new version.
Vault uses pagination to improve performance when retrieving objects.
The default value for the page size is specified in the environment variable
PVAULT_SERVICE_DEFAULT_PAGE_SIZE. When you request a list of objects you can use the
page_size parameter to set the page size as lower than the default value.
The response provides an
results array containing the object details and a
paging object with information about the page. For example:
sizeis the number of results returned.
remaining_countis the number of items that remain to be returned in subsequent pages.
cursoris a reference to the next page. You use the cursor in a follow up call, like this:to obtain the next page.
The final page in a sequence of pages returns
remaining_count and no cursor. For example:
HTTP status codes
The Piiano Vault REST API indicates the success or failure of an API request with a subset of standard HTTP response status codes.
This table lists the HTTP response status codes you may receive from the Piiano Vault REST API.
|Code||Outcome||Example error message|
|200||The request is processed successfully.|
|400||The request fails because part of the request is misformed. For example, required properties are missing from the request body, or a request parameter is in the wrong format.||The access reason is missing.|
|401||The caller's authentication credentials are incorrect or missing. For example, an API key is wrong or not provided.||The request is unauthorized.|
|403||A required policy or policies is missing. For example, the caller needs the ||The operation is forbidden due to missing capabilities.|
|404||An item indicated in the request is not found. For example, a request is made to update items in a nonexistent collection. The error response includes details of the missing items.||No collection exists with the ID [|
|413||The request is rejected as it exceeds a server-side limit.||The request payload is too large. Reduce the size of the payload and try again.|
|414||The URI of the request is longer than the server is willing to interpret.||The request URI is too long. Reduce the request or use a POST operation, if available, and try again.|
|429||The request exceeds the rate limits.||This request exceeds the rate limits. Try again later.|
|500||The request fails because there is an error on the server. This usually indicates a transient error, and you can try again later. If the error persists, contact your service support.||Something went wrong|
|501||The operation hasn't been implemented.||This operation is not implemented.|
|503||The request fails because the service is not running. Try again later and if the error persists, contact your service support.||The operation timed out on the server.|
Error response schema
|integer||The HTTP status code.|
|string||The error message.|
|map||The error context.|
Example Error Response
HTTP/1.1 401 Unauthorized
"message": "Authentication credentials are incorrect or missing.",
Generating client code
The Piiano Vault REST API reference includes a way to convert an API request into a code snippet in the programming language or framework of your choosing.
SQL to Vault mappings
Vault includes data access APIs that provide features similar to those you find in many SQL typed databases.
For those familiar with SQL, the following presents mappings between some common SQL queries and corresponding Piiano Vault REST API calls.
These mappings are divided into:
- Create: queries that insert information.
- Read: queries that return information. These include powerful search options.
- Update: queries that replace information.
- Delete: queries that delete information.
|SQL query||Vault Data API equivalent||Comment|
|Though not shown here, all non-nullable properties in the schema of the collection must be included in the body of this request.|
|Use this operation to insert large numbers of objects into Vault.|
|SQL query||Piiano Data API equivalent||Comment|
|Operation: ||Vault limit access to the entire object record and encourage users to access only specific data. Therefore, requests for all properties are designated as "unsafe" and are only allowed for users with the unsafe access policy.|
|Operation: ||The preferred way to use Vault is to explicitly specifying the properties to read.|
|The "where" property provided in the body supports several common SQL "where" clauses and is rigorously checked to eliminate any chance of SQL injection.|
|SQL query||Vault Data API Equivalent||Comment|
|Include the properties to update in the body.|
|SQL query||Vault Data API Equivalent||Comment|
|Operation: ||Deletes an object by ID.|