Remove duplicate documentation for URI template variables

[RaySinnema]

Assume the RESTBucks service. We'd have an order at /orders/{order-id}/, payments for the order at /orders/{order-id}/payments/, the receipt at /orders/{order-id}/receipt/, and the serving at /orders/{order-id}/serving/. With the current schema, you'd have to document the order-id URI template variable four times.

(It seems that Swagger suffers from the same problem.)

I see at least the following ways to get rid of this duplication:

1. Document the URI template variables once under <service-conventions> and turn <var> into a reference.
2. Capture the parent-child relationships between <resource> elements, for instance using a parent attribute, or using nesting (which is what RAML seems to be doing).

[gentlewind]

The URI templates could be strucuted, but resources are not. So I do not think method (2) is good. Is it possible to make <location> independent of <resource> and make it extensible?

[RaySinnema]

Resources are -by definition- identified by URIs. So if two URIs have a parent/child relationship, so must the resources identified by those URIs. Otherwise the resources aren't properly named.

[gentlewind]

It's right that the two resources probably have the implicit relationship when their URIs derive from the same path prefix, e.g. a document resource, and a version-history resource. But the two resources should not be taken as parent-child relationship on the REST level. For example, version-history resource can exist & be discoverable independently without the exposure of document resource (though odd). So I am nervous about building parent-child relationship for <resource>.

[jonathanrobie]

I agree with William on parent-child relationships. We don't want URI structure to determine meaning.

On Thu, Aug 13, 2015 at 6:26 AM, William Zhou notifications@github.com wrote:

It's right that the two resources probably have the implicit relationship when their URIs derive from the same path prefix, e.g. a document resource, and a version-history resource. But the two resources should not be taken as parent-child relationship on the REST level. For example, version-history resource can exist & be discoverable independently without the exposure of document resource (though odd). So I am nervous about building parent-child relationship for .

— Reply to this email directly or view it on GitHub https://github.com/restful-api-description-language/RADL/issues/30#issuecomment-130605021 .

[RaySinnema]

In summary: we don't want option 2, since we don't want the value of the uri-template to affect the layout of the resource elements. The proposal is option 1: move var under service-conventions. Note that this is a breaking change.

[gentlewind]

+1

[jonathanrobie]

+1