[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: Proposing additional annotations - Core: Prerequisites
|
Hi Jeff, If this is prose documentation, this could be done with a qualifier “Prerequisites” for Core.Description and Core.LongDescription, similar to Remarks and Notes (as discussed in
https://lists.oasis-open.org/archives/odata-comment/201510/msg00002.html). What do you think? Thanks in advance! --Ralf From: Jeff Wight [mailto:jeff.wight@microsoft.com] Hi Ralf, I would expect these to be prose text. It shouldn’t be necessary to do client-side validation in any automated way. From a service stand point, the service itself is responsible for enforcing business logic, thus must already do server-side validation. Furthermore, I actually anticipate that clients wouldn’t necessarily want to use this information to do “validation”, but would bubble it up as information to an end user via some UI. If I use the mail server
example below, the client may want to grey out the Send button if all address fields are empty, or they may want to enable it but present a pop-up with some text. They may have their own, additional pre-requisites they want to add, or they may localize in
languages that that the server didn’t support, thus likely wouldn’t want the exact description found here anyway. Finally, I’m not sure we’d succeed creating a machine-readable language that could describe all of the prerequisites that a service may wish to express. For example, what if the same mail service wanted to express
that Send can only be called once per minute, or that the body cannot contain social security numbers? Thoughts? Thanks, From: Handl, Ralf [mailto:ralf.handl@sap.com]
Hi Jeff, Would these Prerequisites be just prose text, similar to CRUD Descriptions or Remarks/Notes, or would it be a machine-readable language that could be used for automated client-side validation? Thanks in advance! --Ralf From:
odata-comment@lists.oasis-open.org [mailto:odata-comment@lists.oasis-open.org]
On Behalf Of Jeff Wight 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, |
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]