Migrating from API V1 to V2
Overview
The changes from V1 to V2, while breaking, primarily resolve inconsistencies and confusion in the V1 API rather than establishing any new API patterns or interaction styles. Clients using the V1 API should be able to migrate to V2 without changing their workflows at all.
API Consolidation
Endpoint Consolidation
In the V2 API, all REST-like APIs are available from the main API service in the deployment. This means simpler integrations, ingress setups, and client configurations. Specifically, the RBAC Manager API, Notifications API, and Reports API are now served through the same endpoint. Those services will become internal-only services for processing requests in the 5.0 release.
A single swagger/openapi specification now covers all Anchore APIs except the GraphQL API.
Enterprise & Non-Enterprise Route Consolidation
There are no longer any enterprise prefixed routes, and all routes that had a version with and without the enterprise
prefix are now consolidated with no prefix but implement the full enterprise functionality.
Authentication
There are no changes to authentication mechanisms.
HTTP Basic and Oauth2 Tokens using JWT continue to be the authentication mechanisms for using the API. See Authentication
Authorization
There are no changes to the RBAC authorization scheme, actions, and management workflows.
All roles, accounts, and role memberships directly transfer to V2, subject to some field and URL path element renaming for consistency as indicated in the table below.
All the RBAC-related APIs are now served from the main API endpoint per the consolidation section above. There is no longer a need to expose a public port from the RBAC manager service.
Specification
The V2 API is specified using OpenAPI v2/Swagger v2. We anticipate a future migration to specifying the API using OpenAPI v3 to support more modern client generation tooling. However, in the 4.9 release of the V2 API the specification continues to be in Swagger V2.
Required Version in Path
In the V1 API, Anchore services would automatically re-write a version-less request path to use a “v1” prefix. This behavior will no longer be present in the V2 API and in the 5.0 release all clients must specify the requested API version in the path explicitly.
For example, in V1: GET /images –> routed internally to –> GET /v1/images
In V2: GET /images –> HTTP 404. Must use GET /v2/images explicitly.
This is being strictly enforced to allow better future migration between APIs and consistent request handling for clients as the APIs evolve.
Field Renames and Consolidations Overview
This covers the most impactful and significant updates, but is not exhaustive.
Account Name
The “userId” field was a legacy element of a very old version of Anchore. It is now removed and replaced with account_name
in the operations where the return is in fact the account name rather than the ID of the specific user. Since resources
in Anchore are owned by accounts, which may contain multiple users, this is the correct and clear field.
Example: userId ==> account_name
Snake Casing
There is no longer a mix between Camel Casing and Snake Casing for fields in the API. All fields are snake-case for consistency.
Example: imageDigest is now image_digest
Arrays Removed Where Not Appropriate
All APIs that returned an array where the actual response was always a single element have been re-typed to return objects.
Example:
POST /v2/images, returns a single object instead of an array.
APIs that may return large arrays have been wrapped in an object and the array set to the “items” property of the object. This change will allow better non-breaking evolution of the API in the future.