Merge enums by XVincentX · Pull Request #495 · microsoft/api-guidelines

Merge enums by XVincentX · Pull Request #495 · microsoft/api-guidelines


		## Problem

		The API Design requires that a specific property of a data structure has a finite and limited set of values, and such limitation needs to be clearly communicated to the user and give the developer the same structure

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

		## Solution

		In OData, Enums represent a subset of the nominal type they rely on, and are especially useful in cases where certain properties have predefined, limited options.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Enum solution must be based on the evolvable enum. Not evolvable enums are exceptions. Could you please merge all template sections together? it doesn't make sense to have the same section in one document twice.

		#### Cons
		### Cons

		- Adding a new value requires to go through a (generally fast) API Review

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Our internal process shouldn't impact API design considerations especially as they published for external users.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well, it is a clear side effect which is annoying for a lot of workload owners. I can remove it if you want, but we're missing a particular part that affect us. Your call

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please remove this. We might offer some process guidance in the future, but I don't think it's our area of expertise now or something we are working on.


		### Pros

		- Our SDK generators will translate the enum to the best representation of the target programming language, resulting in a better developer experience and free client side validation

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One of the pros for Enums is that clients can write a processing logic based on the enum values.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Isn't that true for any property? Clients write processing logic based on values - not too sure what is different here