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.

note

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>

compliance

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).