Conversation
OlgaPodo
added
Graph 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 |
There was a problem hiding this comment.
Could you please ground the problem in a real design scenario. A good example is at https://github.com/microsoft/api-guidelines/blob/vNext/graph/patterns/alternate-key.md#problem or https://github.com/microsoft/api-guidelines/blob/vNext/graph/patterns/evolvable-enums.md#problem.
| ## 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. | ||
|
|
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
Our internal process shouldn't impact API design considerations especially as they published for external users.
There was a problem hiding this comment.
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
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
One of the pros for Enums is that clients can write a processing logic based on the enum values.
There was a problem hiding this comment.
Isn't that true for any property? Clients write processing logic based on values - not too sure what is different here
2 participants
Closes #494