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

Thu May 6 15:42:57 EDT 2010

Nick,

Perhaps the real point here is how much information we should try to put 
in the resource shape descriptions. In general, any operation on a 
resource will have a set of pre-conditions, e.g. that some properties be 
present or satisfy some condition. We could describe some simple ones in 
the shape, but at some point we'd have to tell consumers to read the spec. 
Having a lot of variant shapes could get out of hand quickly.

The shape should describe necessary, but perhaps not sufficient, 
pre-conditions. So in your multiple creation example, you could have a 
very generic shape with lots of optional properties, and the consumer 
would have to read the spec to determine which ones were required in any 
given state.

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:
Nick Crossley <ncrossley at us.ibm.com>
To:
oslc-core <oslc-core at open-services.net>
Date:
05/06/2010 01:34 PM
Subject:
Re: [oslc-core] Guidelines for  specifying      future-proof 
resources/capabilities
Sent by:
oslc-core-bounces at open-services.net

I'm not sure it is a simple as that.

For example, in Change, different properties of a change request resource 
are required at different stages of its life cycle.  Some are required on 
creation, some are required in later states.  Even the set required on 
creation can vary: one of my colleagues just described the way he needs to 
describe required attributes during creation in Rational Change:

In Change, we can submit new CRs to different states. Each state may have 
different required attributes to create the CR. I think it would be 
modeled like this in OSLC 2:

- Each state we can submit to has a different creationFactory URL (e..g., 
/oslc/crfactory/START_HERE2entered, /oslc/crfactory/START_HERE2assigned).
- Each factory has as associated shape URL.
- Requesting the "shape" returns XML describing how to POST to that URL 
including an element for each attribute that can be submitted.
- Each attribute description has an "occurs" element. For required 
attributes, this would be set to "exactly-one".

Many of these required properties are still editable - they are not 
system-supplied.  For example, the name of the person to whom the change 
request is currently assigned is modifiable, but is required when creating 
a CR in the assigned state.

Note that the shape for query has to be different from both of the shapes 
he described above - since life cycles and process requirements can change 
leaving older objects with a slightly different set of properties, and 
since objects can change state allowing some properties to be deleted, 
there can be very few "exactly-one" required attributes for a query shape 
- almost all would have to be optional.

Nick.

-----oslc-core-bounces at open-services.net wrote: -----

To: Dave <snoopdave at gmail.com>
From: Arthur Ryman <ryman at ca.ibm.com>
Sent by: oslc-core-bounces at open-services.net
Date: 05/06/2010 06:30AM
Cc: oslc-core <oslc-core at open-services.net>, 
oslc-core-bounces at open-services.net
Subject: Re: [oslc-core] Guidelines for specifying future-proof 
resources/capabilities

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

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