8.3 Create on Property URL

To create child resources of an existing resource, SData supports posting to property URLs. For example, the following request will create a new order line and append it to an existing sales order:

POST /sdata/myApp/myContract/-/salesOrders('43660')/orderLines
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/>
  <title/>
  <content/>
  <sdata:payload>
    <salesOrderLine xmlns="http://schemas.sage.com/myContract"
      sdata:uuid="E6A0CB39-429D-4f79-8687-44DCDA81743B">
      <product sdata:key="21"/>
      <orderQty>3</orderQty>
      <unitPrice>13.50</unitPrice>
    </salesOrderLine>
  </sdata:payload>
</entry>

If the operation succeeds, the service provider sends a response such as:

201 Created
Content-Type: application/atom+xml; type=entry
Location: "http://www.example.com/sdata/myApp/myContract/-/salesOrderLines('43660-3')"
ETag: cXi/ZCbYA2nXz9DZYR2pqm==

<entry xmlns:sdata="http://schemas.sage.com/sdata/2008/1" 
       xmlns:http="http://schemas.sage.com/sdata/http/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/-/salesOrderLines('43660-3')</id>
  <title>Sales Order Line 43660-3</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/-/salesOrderLines('43660-3')" />
  <link rel="edit" type="application/atom+xml; type=entry" title="Edit" 
        href="http://www.example.com/sdata/myApp/myContract/-/salesOrderLines('43660-3')" />
  <link rel="http://schemas.sage.com/sdata/link-relations/schema" 
        type="application/xml" title="Schema" 
        href="http://www.example.com/sdata/myApp/myContract/-/salesOrderLines/$schema?version=5" />
  <link rel="http://schemas.sage.com/sdata/link-relations/template" 
        type="application/atom+xml; type=entry" title="Template" 
        href="http://www.example.com/sdata/myApp/myContract/-/salesOrderLines/$template" />
  <link rel="http://schemas.sage.com/sdata/link-relations/post" 
        type="application/atom+xml; type=entry" title="Post" 
        href="http://www.example.com/sdata/myApp/myContract/-/salesOrderLines" />
  <link rel="http://schemas.sage.com/sdata/link-relations/service" 
        type="application/atom+xml; type=feed" title="Service" 
        href="http://www.example.com/sdata/myApp/myContract/-/salesOrderLines/$service" />

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

  <content>Order line 43660-3</content>

  <sdata:payload>
    <salesOrderLine xmlns="http://schemas.sage.com/myContract"
      sdata:uuid="E6A0CB39-429D-4f79-8687-44DCDA81743B"
      sdata:key="43660-3"
      sdata:url="http://www.example.com/sdata/myApp/myContract/-/salesOrderLines('43660-3')"
      <orderNumber>43660</orderNumber>
      <lineNumber>3</lineNumber>
      <product
        sdata:key="21"
        sdata:url="http://www.example.com/sdata/myApp/myContract/-/products('21')" />
      <orderQty>3</orderQty>
      <unitPrice>13.50</unitPrice>
    </salesOrderLine>
  </sdata:payload>
  <http:etag>cXi/ZCbYA2nXz9DZYR2pqm==</http:etag>
</entry>

This feature is restricted to properties that represent parent/child relationships (properties marked with sme:relationship=”child” in the schema).

Relationship properties that support this feature MUST be flagged with sme:canPost=”true” in the schema.

If the relationship is of collection type (flagged with sme:isCollection=”true” in the schema), the created child is appended to the current list of children.

Otherwise, if the relationship is to a single resource (flagged with sme:isCollection=”false” in the schema), the operation only succeeds if the child doesn’t exist before the POST operation. Otherwise, a 409 Conflict error code is returned.

The service should favour a primary URL over a hierachical URL for the id of the created resource (salesOrderLines('43660-3') rather than salesOrders('43660')/orderLines('3')). This is consistent with the recommendations given in the Querying Property URLs and Reading Property URLs sections.

SData providers SHOULD also support template resources on properties that support POST operations. For example, the following GET request would return a template for the example above.

GET /sdata/myApp/myContract/-/salesOrders('43660')/orderLines/$template

SData providers MAY support create operations on property URLs. They MUST support them on all the properties that are flagged with sme:canPost="true" in the schema.

---