8.2 Use of $template URL

The $template URL returns a fresh resource that has been prepared with the application’s default values. This URL is useful if you want to set up the default values in a “create resource” form. For example, a UI consumer can  do a GET on the following URL to fill a “Create Sales Order” form:

GET /sdata/myApp/myContract/-/salesOrders/$template

This GET operation returns a response such as:

200 OK
Content-Type: application/atom+xml; type=entry
 
<entry xmlns:sdata="http://schemas.sage.com/sdata/2008/1" 
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns="http://www.w3.org/2005/Atom">
  <id>http://www.example.com/sdata/myApp/myContract/-/salesOrders/$template</id>
  <title>Sales Order 43660</title>
  <updated>2008-03-31T13:46:45Z</updated>

  <link rel="self" type="application/atom+xml; type=entry" title="Refresh" 
        href="http://www.example.com/sdata/myApp/myContract/-/$template" />
  <link rel="http://schemas.sage.com/sdata/link-relations/schema" 
        type="application/xml" title="Schema" 
        href="http://www.example.com/sdata/myApp/myContract/-/salesOrders/$schema?version=5" />
  <link rel="schemas.sage.com/sdata/link-relations/template" 
        type="application/atom+xml; type=entry" title="Template" 
        href="http://www.example.com/sdata/myApp/myContract/-/salesOrders/$template" />
  <link rel="schemas.sage.com/sdata/link-relations/post" 
        type="application/atom+xml; type=entry" title="Post" 
        href="http://www.example.com/sdata/myApp/myContract/-/salesOrders" />
  <link rel="schemas.sage.com/sdata/link-relations/service" 
        type="application/atom+xml; type=feed" title="Service" 
        href="http://www.example.com/sdata/myApp/myContract/-/salesOrders/$service" />

  <category scheme="http://schemas.sage.com/sdata/categories" 
            term="resource" label="Resource"/>

  <content/>

  <sdata:payload>
    <salesOrder xmlns="http://schemas.sage.com/myContract">
      <orderDate>2008-08-04</orderDate>
    </salesOrder>
  </sdata:payload>
</entry>

The response payload only includes properties that have default values that are different to their datatype’s default value (0, nil). In the example, only <orderDate> is returned and it is set to the current date by the provider.

This GET operation does not create any resource, it just returns an atom entry containing default values. The $template URL can be seen as a _virtual resource_ URL.

The consumer could request the template to include templates for child resources. For example, the following URL:

GET /sdata/myApp/myContract/-/salesOrders/$template?include=orderLines

….would return a slightly richer payload:

    <salesOrder xmlns="http://schemas.sage.com/myContract">
      <orderDate>2008-08-04</orderDate>
      <orderLines>
        <salesOrderLine>
          <orderQty>1</orderQty>
        </salesOrderLine>
      </orderLines>
    </salesOrder>

SData providers MUST support GET operations on the $template URL of all resources kinds that have the sme:canPost attribute set to true  (see Resource Kind Definition).