SData Specification

Previous Page Arrow Next Page Arrow

8.1 Create Example

A resource is created by POSTing an Atom <entry> to the resource kind URL. For example:

POST /sdata/myApp/myContract/-/salesOrders
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>
    <salesOrder xmlns="http://schemas.sage.com/myContract"
      sdata:uuid="BE7D7445-7FA4-4c67-AC22-5F6446314771">
      <orderDate>2008-03-31</orderDate>
      <contact sdata:key="216"/>
      <subTotal>202.70</subTotal>
      <orderLines>
        <salesOrderLine sdata:uuid="5FB95DE2-8548-48ac-8868-8006238EEBF0">
          <product sdata:key="72"/>
          <orderQty>1</orderQty>
          <unitPrice>81.70</unitPrice>
        </salesOrderLine>
        <salesOrderLine sdata:uuid="A2744351-1891-4365-948D-80A32594A14E">
          <product sdata:key="43"/>
          <orderQty>2</orderQty>
          <unitPrice>60.50</unitPrice>
        </salesOrderLine>
      </orderLines>
    </salesOrder>
  </sdata:payload>
</entry>

If the operation succeeds, the service provider sends a response like the following:

201 Created
Content-Type: application/atom+xml; type=entry
Location: http://www.example.com/sdata/myApp/myContract/-/salesOrders('43661')
ETag: 2nXz9DZYR2pqmcXi/ZCbYA== 

<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/-/salesOrders('43661')</id>
  <title>Sales Order 43661</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/-/salesOrders('43661')" />
  <link rel="edit" type="application/atom+xml; type=entry" title="Edit" 
        href="http://www.example.com/sdata/myApp/myContract/-/salesOrders('43661')" />
  <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="http://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="http://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="http://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>1553,1035</content>

  <sdata:payload>
    <salesOrder xmlns="http://schemas.sage.com/myContract"
      sdata:uuid="BE7D7445-7FA4-4c67-AC22-5F6446314771"
      sdata:key="43661"
      sdata:url="http://www.example.com/sdata/myApp/myContract/-/salesOrders('43661')">
      <orderNumber>43661</orderNumber>
      <orderDate>2008-03-31</orderDate>
      <shipDate xsi:nil="true" />
      <contact sdata:key="216"/>
      <subTotal>202.70</subTotal>
      <orderLines sdata:url="http://www.example.com/sdata/myApp/myContract/-/salesOrders('43661')/orderLines">
        <salesOrderLine
          sdata:uuid="5FB95DE2-8548-48ac-8868-8006238EEBF0"
          sdata:key="43661-1"
          sdata:url="http://www.example.com/sdata/myApp/myContract/-/salesOrderLines('43661-1')" />
          <orderNumber>43661</orderNumber>
          <lineNumber>1</lineNumber>
          <product 
            sdata:key="72"
            sdata:url="http://www.example.com/sdata/myApp/myContract/-/products('72')" />
          <orderQty>1</orderQty>
          <unitPrice>81.70</unitPrice>
        </salesOrderLine>
        <salesOrderLine>
          sdata:uuid="A2744351-1891-4365-948D-80A32594A14E"
          sdata:key="43661-2"
          sdata:url="http://www.example.com/sdata/myApp/myContract/-/salesOrderLines('43661-2')" />
          <orderNumber>43661</orderNumber>
          <lineNumber>2</lineNumber>
          <product 
            sdata:key="43"
            sdata:url="http://www.example.com/sdata/myApp/myContract/-/products('43')" />
          <orderQty>2</orderQty>
          <unitPrice>60.50</unitPrice>
        </salesOrderLine>
      </orderLines>
    </salesOrder>
  </sdata:payload>
  <http:etag>2nXz9DZYR2pqmcXi/ZCbYA==</http:etag>
</entry>

A few points are worth mentioning here:

  • In the example, the consumer does not set the primary keys of the resources that it creates in the posted payload. This is because the primary keys are generated by the service provider from an automatically incremented counter. The consumer can get the primary keys assigned by the service from the sdata:key attributes in the response message.

  • In the example, the consumer generates a universally unique identifer (UUID) for the salesOrder resource and its line sub-resources. It then it passes these UUIDs to the service provider via the sdata:uuid attribute. This is not imposed by SData but is good practice as it makes the POST operation idempotent (safe to be called several times). That is, no harm is done if the same request is received twice by the service provider.

  • The <id>, <title> and <updated> elements of the Atom entry don’t need to be filled by the consumer before submitting the request. The only data that matters is the XML payload; the <salesOrder> element.

  • The response MUST include a Location HTTP header. This header contains the URL that the consumer can use to read the resource.

  • The response MUST include an Atom <entry>. The contents of this entry are usually different from the submitted entry because it will contain data that was not submitted by the consumer but set up by business rules on the provider side (primary key values for example).

  • The above request creates three resources: one salesOrder resource and two salesOrderLine resources. In a POST operation, the service should create child resources, if present in the posted payload. Whereas the service should ignore resources that are related by a parent, reference or association relationship. See description of relationship attribute in the Relationship Definition section.

  • The consumer can optimize the data transfer by passing adding the returnDelta=true query parameter to the POST URL. This parameter tells the SData provider to return only the properties that differ from the posted payload, i.e. properties that were not included in the posted payload or properties for which the provider overruled the value passed by the consumer. This feature is OPTIONAL on the provider side. Providers that do not support this parameter MUST ignore the returnDelta parameter and respond with the normal payload, as if returnDelta had not been specified. See details in the Query Parameters section.

SData providers MUST support this create protocol on all resource kinds that have the sme:canPost flag set to true. The request and response MUST conform to the rules given above.
Previous Page Arrow Next Page Arrow