Resource Creation

Conventional REST wisdom holds that resource creation is generally a simple task. In most cases, you POST a document to a URL. The most likely response codes are 201, indicating a successful creation (including the URL of the newly created resource) or a 400 error of some kind indicating that the creation failed.

However, in many cases, we can not assume that the client has enough data to ensure successful creation of the resource. In particular, imagine where a user in a quality management tool wants to create a record in a defect tracking system or a requirements management system. In most systems, resources like work items, change requests, and requirements are all highly configurable with required attributes and other associated process rules.

Under these circumstances, there are two ways that a client could know how to create a well-formed resource:

1. It could read a description of the acceptable shape of these resources and the associated process rules. Currently, none of these systems have compatible schema systems, type systems, or process rules.
2. We could agree, in advance, that a certain format is definitionally acceptable for a certain resource type. Any differences between the agreed-upon resource format and the rules of the underlying storage mechanism would be the responsibility of the OSLC implementation to sort out.

Option #2 requires several parties to agree on the acceptable resource definition. This is difficult, but not impossible. Option #1 requires several parties to agree on how we describe acceptable resources – this is significantly more complicated.

Part of the hope of OSLC is to enable simple integrations among tools so that, for example, a tester can file a defect when a test fails or submit a requirement that they encounter during testing, or so that a customer representative in a call can submit change requests into the development team’s CM system. These scenarios all have some things in common.

• Client needs an API to create a certain kind of resource.
• Client tool may want the URI of the resource to be created. This may be found at POST time, or at a later time.
  • Loosening this requirement, we could say that the foreign tool needs a way of finding the resource that was created. If the foreign tool can be expected to understand the server’s query mechanism, it might use query to find this resource. However, that is only viable if the client put data in the resource making it uniquely identifiable. In the case of (eg) a test case referencing a defect, many test cases may be referenced by the same defect, making such a query ambiguous. Also, failing to include the capability to find resources created through this protocol introduces a dependency on the query capability.
• Client tool MAY know more about the server in which the resource is being created, and in those cases should be able to create the resource without user intervention.

This leaves us with a few options, including:

1. Agree on the format that will, definitionally, be accepted as a POST; (Any differences between the agreed-upon resource format and the rules of the underlying storage mechanism would be the responsibility of the OSLC implementation to handle).
2. Standardize the way that we describe the shape of a valid resource so the client can learn what is needed in advance of the POST; (Currently, most of these systems have incompatible schema systems, type systems, or process rules);
3. Standardize a response document that explains the problems with an invalid POSTed document, allowing a client to discover how to make a resource valid after the POST fails;
4. Have the server accept the data even if it is bad, return a “regular” URL on that data (one that will always be associated with this resource).
5. Say that we do not use POST in these cases – client will always GET a Web UI (possibly with seed data) that allows the user to create the resource;
6. Standardize a way for the client to handoff creation of the resource to the tool that already knows how to create the resource, while retaining its URL.

Option A is quite powerful – the more often we can get agreement on even minimal resource formats, the better our interoperability story will be. However, we recognize that this will not be possible in all cases. When this works, we call this “unattended resource creation” since no user is involved in creation of the resource after the data is POSTed.

Options B and C are closely related – they require standardizing a metadata story of some kind. While ultimately very powerful, this would require substantial agreement amongst the participants in OSLC across the various domains and would place a substantial implementation burden on the clients. We feel this is out of scope for OSLC 1.0

Option D is problematic – we believe there are many applications for which this is an impossibility, even with the assistance of a mapping layer.

Option E does not give any programmatic way of determining the URL of the resource being created – creation is completely handed off to a user. If this is not a requirement, Option D works, but it does require some way for the client to discover if it knows how to create a POSTable resource or not (which might or might not be the same as discovering if the server allows resource creation via POST).

Option F seems to be the only viable option when Option A is unavailable. Because the protocol for this would explicitly involve a user, we call this “attended resource creation.”

The two viable options are A, “Unattended Resource Creation” and B “Attended Resource Creation.”

Unattended Resource Creation

This is a fairly simple interaction – the client POSTs the agreed-upon resource format to the factory URL, and receives 201 (Created) along with the URI of the newly minted resource. This is the traditional RESTful Resource Creation.

Attended (or delegated) Resource Creation

The drafts mechanism in RTC achieves attended resource creation, although it did so by introducing some concepts specific to its implementation (in particular, the notion of the draft workitem). This concept is not easily implementable in other systems, however.

Here is the proposal for the attended resource creation protocol:

1. Client POSTs a resource “stub” – typically a subset of a predefined resource format – to a factory URL on the server. It may be helpful to view this as a "form factory" rather than as a "resource factory."
   1. This URL is likely provided as part of a configuration step, connecting the client to the server.
   2. This URL likely identifies a context to the server, including details that we don’t want to require the client to be aware of, such as the RTC Project Area or CQ User Data Base.
2. The server returns 201 (Created) along with the URI of a form which, when opened in a browser, allows a user to complete the data entry process, resulting in a well-formed resource. This form is an HTML resource that includes Java Script to communicate the URL of the created change request back to the client. The protocol for this communication is documented as part of the OSLC-CM 1.0 Delegated Resource Selction and Creation spec.

The approximate flow in this scenario is:

-- SteveAbrams - 05 Feb 2009