The following standards and practices are applied across our APIs unless otherwise noted in API Reference Documentation
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.
More information on User Authentication can be found in the next section: Authentication
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.
Developer.com's introduction to REST is recommended reading for those wishing to learn more about REST.
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.
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.
More information can be found at the OpenAPI website
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
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.
Semver's summary of Semantic Versioning best describes how versions reflect changes made to software