Creating a New Resource

Creating a New Resource

One of the principles of REST is the use of simple and uniform interfaces.
In the REST API, new resources are created using the HTTP POST method.

Example: Create a Service Request

POST http://myserver:5181/odata/ServiceRequests  HTTP/1.1
Content-Length: 247
Content-Type: application/json


{
    "Description": "Printer is not working properly.",
    "Information": "The printer in room 14C is causing paperjams all the time.",
    "Medium": {
        "Text": "External",
        "Value": 12783238
    },
    "Status": {
        "Value": 3120234513,
        "Text": "Waiting"
    },
    "Impact": {
        "Value": 3094610021
    }
}
  • Codes can be assigned by id value, localized text, or both.
  • A resource must not contain a key during creation.
  • All required fields must be provided.

The response will contain the created item, including values automatically assigned by the server:

{
  "Description": "Printer is not working properly.",
  "Information": "The printer in room 14C is causing paperjams all the time.",
  "Status": {
    "Text": "Waiting",
    "Value": 3120234513
  },
  "Medium": {
    "Text": "External",
    "Value": 12783238
  },
  "Impact": {
    "Text": "Low ( 1 person affected)",
    "Value": 3094610021
  }
}

Custom Codes

Custom codes require the @odata.type annotation:

{
  "Description": "Printer is not working properly.",
  "Information": "The printer in room 14C is causing paperjams all the time.",
  "ServicecallCode1": {
    "@odata.type": "#PROLIN.Web.OData.Model.Code",
    "Text": "Code 1",
    "Value": 3120234513
  }
}

Entity References and Relationships

Entity references can be created with @odata.bind.

{
  "Description": "Printer is not working properly.",
  "Information": "The printer in room 14C is causing paperjams all the time.",
  "Status": {
    "Text": "Waiting",
    "Value": 3120234513
  },
  "Caller@odata.bind": "/Persons(234)",
  "Workorders@odata.bind": [
"http://myserver:5181/odata/Workorders(123)",
"http://myserver:5181/odata/Workorders(456)"
]
}

Properties Left Out and Explicit Nulls

The server writes exactly the properties the request body contains:

In the request body With a template Without a template
Property left out The template’s value is kept Nothing is written; the server’s default or derived value is kept
"Property": null null is written, also over the template’s value null is written
"Property": <value> The value is written, over the template’s value The value is written

Leave out a property you do not want to set. Do not send null for it: an explicit null is applied as sent.

The properties of a complex value, such as Assignment, follow the same rules:

{
  "Description": "Printer is not working properly.",
  "Assignment": {
    "ReferenceNumber": "INC-4711",
    "AssigneePerson@odata.bind": "/Persons(234)"
  }
}

A property value the server cannot store makes the request fail, and nothing is created; see Values That Cannot Be Stored.

Caller and Caller Organization of a Service Request

Binding only the caller is enough. When the caller belongs to an organization, the server fills in CallerOrganization with that organization:

{
  "Description": "Printer is not working properly.",
  "Status": {
    "Value": 3120234513
  },
  "Caller@odata.bind": "/Persons(234)"
}

You can also bind CallerOrganization yourself, but only to the caller’s own organization. A service request keeps a caller only together with the caller’s own organization: when the request sets CallerOrganization to another organization, or to an explicit null while the caller belongs to an organization, the service request is created without a caller.

NoteDifference from OData 4.0

OData 4.0 requires a create to fail when the service cannot store every property value the request specifies. The REST API answers 201 Created in the cases above, and the stored service request has no caller. Bind the caller alone, or together with the caller’s own organization, and read the created resource back to confirm what was stored.

Properties the Server Sets on an E-mail Service Request

The server sets FromAddress, Date, Incoming and Source of a new e-mail service request itself, as in the Smart Client, where these fields of a new e-mail cannot be edited. A request that sets one of them to a value fails with 400 Bad Request and creates nothing; see Values That Cannot Be Stored. Leave them out of the request: the property gets the template’s value, or the value the server gives it. To create an e-mail with a particular From address, use a template that sets it.

The service request an e-mail belongs to (ServiceRequest@odata.bind) can always be set, also when the e-mail is created from a template.

Returning Created Objects

When creating a new entity, you can add a Prefer header to request that the created object be returned.
The returned object may not yet include changes made by database rules (DB Rules); see the note on DB Rules.

Create Using a Template

You can create new entities using a template. Templates define the structure, and additional values posted override template values. A property set to an explicit null clears the template’s value; a property left out keeps it (see Properties Left Out and Explicit Nulls).

NoteDifference from OData 4.0

A collection sent empty (for example "Workorders@odata.bind": []) does not remove the members a template creates. The created resource keeps them, although the request specified an empty collection.

Example: Create a Configuration Item using the ROUTER template

POST http://myserver:5181/odata/ConfigurationItems  HTTP/1.1
Content-Type: application/json


{
 "Template@odata.bind": "/Templates(3101753354)",
 "Searchcode": "RESTAPI",
 "Name1": "REST API Router",
 "IPAddress" : "192.168.1.1"
}

The template is referenced by its Id.

To list available templates for a specific entity type:

GET http://myserver:5181/odata/Templates?$filter=Entity/Name eq '[Entity Name]'

Where [Entity Name] matches one of the supported entities.

Back to top