16 Similar Error Definitions with Same & Different Names in Swagger Specs

[selvasingh]

#16 Similar Error Definitions with Same & Different Names in Swagger Specs

There are several similar error definitions across Azure Swagger specs with same & different names.

In languages like Java and C#, similar error definitions with same & different names generate similar, multiple exception class definitions with same & different names in different name spaces.

Azure libraries for Java and other such languages carry a large surface area. A major part of API ergonomics is consistent naming themes, uniform definition of errors, uniform error handling, etc. Consistency makes it easier to use and memorize and also enables portability of learning. Having learnt a part of the library, developers can apply that learning across other parts of the libraries.

In Swagger specifications, designers should avoid duplicate definition of errors with same or different names. This, in turn, helps language-specific client library generators to choose an already existing exception class for each kind of abnormal condition that may cause an operation to thrown an error; define new exception classes, if needed.

The table below describes the current state - 16 similar error definitions with different names. These definitions can be represented with a single base error definition that comprises of {code, message, source-of-error, description, details} and Swagger specs MAY extend the definition to differentiate or pack additional info.

#	Service	Error	Code	Message	Source-of-error	Description	Details	Additional-info
1	CDN	ErrorResponse	Y	Y
2	Compute	ApiError	Y	Y	Y	Y	Y
3	Data Lake Analytics Account	Error	Y	Y	Y	Y	Y
4	Data Lake Job	Job Error Details			Y	Y	Y	Plenty of info
5	Data Lake Store Account	Error	Y	Y	Y	Y	Y	Y
6	Intune	Error	Y	Y
7	Mobile Management	ApiError	Y	Y
8	Network	Error	Y	Y	Y	Y	Y
9	Resources - Resources	ResourceManagementErrorWithDetails	Y	Y	Y	Y
10	Batch	DeleteCertificateError	Y	Y		Y	Y
11	Batch	JobSchedulingError	Y	Y		Y	Y
12	Batch	TaskSchedulingError	Y	Y		Y	Y
13	Batch	AutoScaleRunError	Y	Y		Y	Y
14	Batch	ResizeError	Y	Y		Y	Y
15	Batch	ComputeNodeError	Y	Y		Y	Y
16	Batch	BatchError	Y	Y		Y	Y

[brjohnstmsft]

These definitions can be represented with a single base error definition that comprises of {code, message, source-of-error, description, details} and Swagger specs MAY extend the definition to differentiate or pack additional info.

@selvasingh: Bruce from the Search team here. The only commonality the type ItemError has with the others is an error message. Why would we change it to inherit from a type that has far more properties? That seems to go against the goal of making the Swagger spec accurately model the REST API.

FYI @chaosrealm @devigned

[selvasingh]

@brjohnstmsft BTW, there are two common items - message and description. Regardless, ItemError is different from other error definitions. So, removed it off the list

[devigned]

@Azure/adx-autorest-contributors and @Azure/openapi-advisors any thoughts on this issue?

[matthchr]

@selvasingh @devigned
I work on the Batch team, so addressing some of the error types which were listed above from the Azure Batch service swagger specification.

The Errors you listed are almost all errors in the body of entities rather than errors which generate exception types. For example, the following errors do not map onto exceptions:

1. DeleteCertificateError
2. JobSchedulingError
3. TaskSchedulingError
4. AutoScaleRunError
5. ResizeError
6. ComputeNodeError

These types are used because our service performs many operations asynchronously on behalf of the user and because the operation is not being performed in the context of a particular user API call, it doesn't make sense to propagate errors which occur as part of an asyncronous workflow as an exception. Thus they follow the FooError naming, but are not exceptions but are rather just properties.

The one that does map onto an exception is: BatchError

I believe that the topic of a common Exception or Error base class for use across libraries has been discussed, and if such a thing were to exist (for example in the client runtimes of each language with a code and message field), then BatchError ought to inherit from that (or maybe just use the base if it matches exactly).

[kirthik]

Closing this since we are tracking it here - Azure/autorest#1523