[oslc-core] Guidelines for specifying future-proof resources/capabilities

[Arthur Ryman]

Dave,

I think the spirit of REST is that you create via PUT or POST and that GET 
is more or less the inverse of PUT. The only exception is that when you 
GET the resource, it may have acquired some additional properties, e.g. 
creator, creation date, an identifier, etc. The way I was distinguishing 
these in the EMS spec is via the editability of the property, not its 
occurrence. The properties that are maintained by the service are 
read-only and they should not be provided on creation since they are 
generated by the system. Normal properties are read-write. You could also 
imagine write-once properties that you only set on creation and that 
cannot be changed later.

Given that we can distinguish client-provided (read-write) versus 
system-generated (read-only) properties, then there should be no need to 
have different creation and query resource shapes.

Regards, 
___________________________________________________________________________ 

Arthur Ryman, PhD, DE


Chief Architect, Project and Portfolio Management

IBM Software, Rational

Markham, ON, Canada | Office: 905-413-3077, Cell: 416-939-5063
Twitter | Facebook | YouTube







From:
Dave <snoopdave at gmail.com>
To:
oslc-core <oslc-core at open-services.net>
Date:
05/06/2010 08:04 AM
Subject:
[oslc-core] Guidelines for specifying future-proof resources/capabilities
Sent by:
oslc-core-bounces at open-services.net



re: Specification versioning

I'm still working representations today, but I've been thinking more
about the guidance that we should provide in Core spec to help
workgroups specify "future proof" resources.

The rule

   * A new version of an OSLC specification is not allowed to
introduce changes that will break old clients.

The guidelines

For OSLC workgroups, these are some guidelines to help you live with
the above rule and specify OSLC resources that are as future-proof as
possible.

   1) Think you need a property but cannot agree on the value-type?
This is a strong indication that you should not attempt to standardize
on the property. Once decide on a value-type you are stuck with it
forever. Wait until you have the scenarios or implementation
experience needed to agree upon a value-type.

    2) When introducing a new capability, e.g. a creation factory,
query capability or delegated UI dialog; one that works differently
than those specified in the Core spec or older versions of your own
spec, you should create a new resource type to represent the service.
This will enable old clients to continue to work against old services
and new clients to work with your new capabilities.

   3a) When defining resources, you are not allowed to remove, change
the meaning or the value-type of any properties that you defined in
earlier versions of the specification. You can add new properties but
not change those that already exist.

   3b) When defining resources, consider which ones are required to
provided by clients at creation or update time vs. those which are
required to be in representations returned by the server. When
creating a new version of a specification: it's OK to relax
restrictions on clients but it is not OK to add new required
properties because that will break old clients.

ISSUE: we should pick either 3a or 3b. At this point, I think 3b seems
more reasonable and gives workgroups some more leeway in making
changes, but...

ISSUE: how can we enable 3b? Do we recommend that OSLC domains provide
different shapes for creation vs. query? Do we require that domains
specify two ""occurs" values for each property: oslc:creationOccurs
and oslc:queryOccurs? Does this overlap with the oslc:queryable value
that we discussed yesterday?

I'd like to write this up (and the rest of the changes in
http://open-services.net/bin/view/Main/OslcCoreMeetings04302010) this
week, so any feedback, comments, suggestions, etc. you might share are
all most welcome.

Thanks,
- Dave

_______________________________________________
Oslc-Core mailing list
Oslc-Core at open-services.net
http://open-services.net/mailman/listinfo/oslc-core_open-services.net