OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

odata-comment message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: RE: Proposing additional annotations - Core: ErrorCodes


Hi Jeff,

 

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!
--Ralf

 

From: odata-comment@lists.oasis-open.org [mailto:odata-comment@lists.oasis-open.org] On Behalf Of Jeff Wight
Sent: Dienstag, 27. Oktober 2015 19:06
To: odata-comment@lists.oasis-open.org
Cc: Mark Stafford <mastaffo@microsoft.com>; Michael Pizzo <mikep@microsoft.com>
Subject: [odata-comment] Proposing additional annotations - Capabilities(SelectRestriction, UpsertSupported) - Core(ErrorCodes, CRUD Descriptions, Prerequisites)

 

Hi,

 

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:

Capabilities:

·         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.

 

Core:

·         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

 

Thoughts?

 

Thanks,
~Jeff

 



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]