VikingCloud Portal API Standards

The following standards and practices are applied across our APIs unless otherwise noted in API Reference Documentation

VikingCloud Portal APIs are secured

VikingCloud Portal APIs require users to authenticate using valid VikingCloud Portal user credentials to obtain tokens, which must be passed with requests. When applicable, APIs will restrict data access (read/write/etc.) to only those entitled to that data.

APIs follow RESTful principles

REpresentational State Transfer (or REST) is an architectural style, not a standard. While it allows for flexibility, there are general guidelines and patterns that have been adopted by those using REST.

Data is exchanged with JSON payloads

Most APIs exchange data in the JSON (JavaScript Object Notation) format due to size, support, and readability (human and machine). The request and response schemas for specific APIs can be found in the API Reference Documentation

APIs are documented with the OpenAPI standard

VikingCloud product teams use the OpenAPI specification (v 3.0.+) to document their APIs. There are a variety of tools that API consumers may use to visualize or edit an OpenAPI specification, as well as tools for code generation and testing.

What is the OpenAPI Specification?

From the OpenAPI specification website:

The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.

An OpenAPI definition can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases.

We follow Semantic Versioning for changes to our APIs

Semantic versioning allows us to communicate the types of changes that have been made to our APIs during development. Each set of reference documentation will show the full current version of the API, in the form 1.2.3.

Since major version changes are the most significant type - they include breaking changes to contracts or functionality of the API - we convey the major version in both URI of API requests i.e. https://api.vikingcloud.com/wrm/v1/sponsors) and in the reference documentation. This helps API consumers quickly identify which version of an API they are using.