[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: Proposing additional annotations - Core: ErrorCodes
Thus far, we only really thought of ErrorCodes for Operations.
It might be possible to consider using Qualifier for entity CRUD though. Something like:
<Annotation Term=”Core.ErrorCodes” Qualifier=”Update”>…</Annotation>
<Annotation Term=”Core.ErrorCodes” Qualifier=”Delete”>…</Annotation>
<Annotation Term=”Core.ErrorCodes” Qualifier=”Create”>…</Annotation>
You are correct that this list should be assumed as incomplete.
I like it.
For entity sets: would you want to specify for which operation(s) (Create, Read, Update, Upsert, Delete) the code may be expected, or would that rather be expressed in the prose description?
And I assume that by definition this is a potentially incomplete list, and the service may produce error codes not documented here?
We’re looking to document the potential values of the ErrorCode property in the standard OData error response.
The descriptions of potential HTTP response codes is pretty industry standard, and while not all services do a perfect job of responding with the correct one, I don’t think it’s prudent to provide a mechanism that encourages services to re-describe / re-define these.
Furthermore, if a service does wish to do that, they could simply make their ErrorCodes match the Http response code, then document them the same way here.
Instead, I know that at least our service will respond with very specific ErrorCodes for each type of error. For example, when a client issues a request to a URL with an invalid property name specified in a filter, or a POST with an invalid property name specified in the body of the request, they both respond with 400 Bad Request, but we will respond with unique ErrorCodes in these two examples.
As an example of what I’d expect to see in $metadata, it could be something like:
<PropertyValue Property=”ErrorCode” String=”QueryFilterFunctionNotSupported”/>
<PropertyValue Property=”Description” String=”This error indicates that a request was made with a filter function that isn’t supported on this entity set. Please refer to the Capabilities.FilterFunctions annotation on this entity set for a list of supported functions, and the exact error message for which function usage triggered this error.”/>
Just for clarification: would you want to document the potential HTTP response codes, or rather the potential values of the error/code property in the standard OData error response?
Thanks in advance!
While going through exercises to better document our OData service, we came up with a collection of annotations we think we’d need in order to specify the rich content we’d like to express.
Here is a summary of some of the needs that I believe will be useful to any OData service:
· SelectRestrictions – Similar to Filter, Sort, and Expand Restrictions, we need the ability to specify if a collection supports $select, and which properties are non-selectable.
· UpsertSupported – Fairly self-explanatory, a tag to indicate whether a given entity set supports Upsert. We’d also like to considering how to differentiate PATCH vs PUT flavors of Upsert.
· CRUD Descriptions – We already have the ability to identify which CRUD operations are supported on an entity set, using Insert, Update, and Delete Restrictions, but we’d like to be able to provide specific comments about these actions. For example, a service that manages distribution lists may allow you POST to the /Users collection, meaning you are creating a user, however if you POST to the Distribution/BlockedSenders collection, this means you are blacklisting that user from being able to send mail to that group. While one could imply this using the description of the entity set itself, it would allow us to be a bit more descriptive / contextual / clear here.
· Operation ErrorCodes – Similar to how C# summary comments allow you to specify any <exception>s that a method may potentially throw, we would like to be able to specify the ErrorCodes that a given Operation may return, along with a blurb on what that error code means / how to resolve it.
· Operation Prerequisites – Any special conditions that must be met before a caller should expect they can call an operation. For example, an email service may expose a Send operation on an Email entity, but in order to invoke it, the email must have at least one of To:, CC:, or BCC: set.
In addition to the above, we have a need to expose the following as well, though I’m not sure they would be as generally useful to any OData service, but including here for discussion:
· Entity Remarks – This is slightly different than Description or LongDescription, but similar to the <remarks> tag in c# summary documentation.
· OAuth Scopes – Since our OData service support OAuth2, we’d like to be able to describe which OAuth scopes are required for interacting with an entity. For example, an Email requires Mail.Read while an Event requires Calendar.Read. It would also be nice to be able to specify that UPDATE and DELETE require the .ReadWrite permission.
· Generic Schema Notes – These would be generic notes / footnotes on an entity that would apply to StructuralProperties, NavigationProperties, and Operations. I would imagine this as StructuralPropertyNotes, NavigationPropertyNotes, and OperationNotes