Feature Request: Standardize REST API design, payload structure and documentation across all REST APIs

[DE&C]

TL;DR

• Standardize the design of all Veeam REST APIs.
• Keep payload structures and naming conventions consistent within each API.
• Avoid unnecessary breaking changes between API revisions.
• Document complete request and response schemas, including type-specific properties, allowed values and semantic meanings.
• Ensure that the OpenAPI specification can be reliably used for validation, strongly typed models and SDK generation.
• The Repository API is used only as an example. This request applies to all REST APIs.

Summary

This feature request proposes a general standardization of all Veeam REST APIs regarding payload structure, naming conventions, API consistency and documentation.

The Backup Infrastructure / Repositories endpoint is used only as an example. The request applies to the complete REST API surface.

Some API responses appear to reflect internal implementation models instead of exposing a consistent and stable external API contract.

Details and examples

1. Use a consistent payload structure

Objects representing the same resource should follow the same structural pattern.

The payload hierarchy should remain consistent regardless of the underlying object type. Only values and genuinely type-specific settings should differ.

Current

The payload structure changes depending on the repository type. The repository type is represented both by a type-specific property name and by the "type" property.

Code: Select all

{
"dellDataDomain": {
...
},
"repository": {
...
},
"mountServer": {
...
},
"type": "DellDataDomain"
}

{
"hpeStoreOnce": {
...
},
"repository": {
...
},
"mountServer": {
...
},
"type": "HPEStoreOnce"
}

A client must therefore evaluate the "type" value and also know which corresponding type-specific property name to expect.

Proposed

The payload hierarchy should remain consistent for all repository types. The value of "type" identifies the repository type, while properties that cannot be standardized are placed in a clearly named type-specific object.

Code: Select all

{
"type": "DellDataDomain",
"repository": {
...
},
"mountServer": {
...
},
"typeSpecificSettings": {
"ddBoostEncryptionEnabled": true,
"ddBoostEncryptionType": "Medium"
}
}

{
"type": "HPEStoreOnce",
"repository": {
...
},
"mountServer": {
...
},
"typeSpecificSettings": {
"useFCConnectivity": false,
"useStoreOnceWanLink": false
}
}

Only settings that genuinely cannot be represented through standardized properties should be placed inside "typeSpecificSettings".

This keeps the payload hierarchy stable, avoids type information being represented through changing property names and simplifies client implementations.

2. Standardize naming conventions

Within the same API, identical concepts should use identical property names.

Examples from the current Repository API include:

• taskLimitEnabled vs. enableTaskLimit
• readWriteLimitEnabled vs. enableReadWriteLimit
• mountServer vs. mountServers

These differences unnecessarily increase client-side complexity.

The goal is not to use identical property names across every unrelated REST API. Each individual API should, however, follow a consistent naming convention within its own resource model.

3. Keep the payload hierarchy stable

Equivalent information should appear at the same location within the payload.

Clients should not have to inspect the repository type to determine whether a setting is located at the root level, inside "repository" or inside another type-dependent object.

A stable hierarchy would make parsing, validation and strongly typed client models considerably simpler.

4. Keep identifiers stable across API revisions

Property names, object names, type identifiers and enum values should remain stable across API revisions whenever possible.

For example:

API revision 1.3-rev1:

Code: Select all

DDBoost

API revision 1.3-rev2:

Code: Select all

DellDataDomain

"DellDataDomain" may be a clearer identifier. However, changing an existing identifier requires API consumers to update integrations even though the underlying repository type remains the same.

Changes of this kind should only be introduced when necessary and should be accompanied by a documented deprecation, compatibility or migration strategy.

The same principle should apply to property names and payload structures.

5. Improve documentation

The REST API documentation should describe the complete request and response schema for every supported object type.

One challenging example is:

Code: Select all

/api/v1/backupInfrastructure/repositories

For the "typeFilter" query parameter, the documentation lists the possible "ERepositoryType" enum values.

For example:

Code: Select all

Array of strings (ERepositoryType)

Items Enum:

WinLocal
LinuxLocal
Smb
Nfs
AzureBlob
AzureDataBox
AzureArchive
AmazonS3
AmazonSnowballEdge
AmazonS3Glacier
S3Compatible
GoogleCloud
IBMCloud
ExtendableRepository
DellDataDomain
ExaGrid
HPEStoreOnce
QuantumDXi
WasabiCloud
LinuxHardened
...

The documentation also provides a general response sample. However, that sample covers only selected repository types and does not describe the complete response schema for every value of "ERepositoryType".

Depending on the repository type, different top-level properties, nested objects and settings may be returned. The documentation does not currently provide a complete mapping that explains:

• Which properties are returned for each repository type
• The data type of every property
• Which properties are required or optional
• Which values are allowed
• The meaning of each property
• Complete request and response examples for each supported repository type

API consumers must therefore inspect live responses to determine the actual payload structure for repository types that are not covered by the available examples.

Another example is the use of undocumented semantic values:

Code: Select all

{
"maxTaskCount": -1
}

The property is an integer, but the documentation does not explain the meaning of "-1".

It is therefore unclear whether "-1" represents an unlimited value, a disabled setting, an automatically selected value, a default value or another state.

The documentation should include:

• Complete request schemas
• Complete response schemas
• All properties for every supported object type
• Data types
• Required and optional fields
• Allowed values and valid ranges
• Default values
• The semantic meaning of every property
• The meaning of reserved values such as -1 or 0
• Complete examples for every supported object type

An API specification should describe the complete API contract, not only the available endpoints, filter parameters and enum values.

6. Provide a complete and reliable OpenAPI specification

A major advantage of OpenAPI is the ability to generate client libraries, strongly typed models, validators and SDKs automatically.

This benefit is significantly reduced when:

• Polymorphic response structures are not completely represented in the schema
• Properties depend on undocumented object types
• The same concept uses different property names
• Special values and valid ranges are not defined
• Examples cover only a subset of the possible response structures

The OpenAPI specification should fully describe all supported request and response variants.

Where polymorphism is required, standard OpenAPI mechanisms such as explicit schemas, discriminators and "oneOf" definitions should be used so that tools can reliably determine which payload belongs to which type.

Practical experience

We have been developing an application based on the Veeam Backup & Replication REST APIs for more than a year.

A significant portion of our overall development effort has been spent dealing with inconsistent payloads, undocumented response structures, changing identifiers and varying object hierarchies instead of implementing application functionality.

The issues described in this request originate directly from practical experience in a real-world project.

Standardizing the REST APIs and completing the documentation would significantly improve our development productivity. It would also simplify validation, testing, integration and long-term maintenance for other API consumers.

Expected outcome

The goal is to make all REST APIs follow a consistent, predictable and documented design.

This includes:

• Consistent payload structures within each API
• Consistent naming conventions within each API
• Stable property names and identifiers across API revisions
• Standardized modelling wherever possible
• Clearly separated type-specific settings only where necessary
• Complete documentation of request and response schemas
• Documentation of allowed, default and reserved values
• A complete OpenAPI specification suitable for validation and code generation

The Repository API is only one example where these challenges become visible.