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 <[email protected]> To: oslc-core <[email protected]> Date: 05/06/2010 08:04 AM Subject: [oslc-core] Guidelines for specifying future-proof resources/capabilities Sent by: [email protected] 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 [email protected] http://open-services.net/mailman/listinfo/oslc-core_open-services.net
