HTTP API POST

POST Basics

The POST verb is used to create new resources. The POST method is called on the collection resource.

To create a new "title" resource, one can POST the following resource representation to "[api-context-root]/generic/titles":

{ "code" : "MYCODE",
   "displayCode" : "My Code"
}

When the new resource successfully is created, status code 201 is returned and the URI of the new resource is returned in the Location header:

Location: http://<host>:<port>/[api-context-root]/titles/<new id>

The response body contains a representation of the created resource in the default representation as described in section Default Resource Representation (GET):

{
  "id": <new id>,
  "active": "Y",
  "code": "MYCODE",
  "displayCode": "My Code",
  "displayOrder": 1,
  "displayPosition": "A",
  "objectVersionNumber": 1,
  "links": [
    {
      "href": "http://<host>:<port>/[api-context-root]/generic/titles/<new id>",
      "rel": "self",
    }
  ]
}

This enables clients to inspect generated default values without an additional request.

Include Sub Resources

POST can also be used to create sub resources. The top level resource and all the included resources are persisted in one transaction using POST.

The following example shows a payload that creates a claim with a single claim line:

{
  "externalPricing" : "N",
    "claimDate" : "2010-04-30",
    ... ... .... ... ... ...
    "claimLines" : [ {
        "subscriptionDate": "2009-07-01",
        "keepBenefits": "N",
        ... ... .... ... ... ...
       ]
     }
}

Discover Properties

Using Metadata

Which properties can be included in a POST payload can be discovered from the its metadata. For example,

http://<host>:<port>/[api-context-root]/generic/messagegroups/metadata.

Using the create-form Link

As an alternative to using the metadata, HTTP API can also generate a blank resource representation as a starting point for the POST operation. Clients can request that resource, fill in the values and POST it to the collection resource.

The root resource of all HTTP API resources includes a link of type "create-form":

{
    "name": "",
    "links": [
        {
            "rel": "canonical",
            "href": "http://:/[api-context-root]/generic/"
        },
...
        {
            "rel": "create-form",
            "href": "http://:/[api-context-root]/generic//create-form"
        },
    ]
}

The "create-form" link is only present for resources that support POST.

Note

The "create-form" link is not dependent on the access rights of the current user.

  1. The "create-form" resource returns a representation with all properties that HTTP API will process when present in the POST method. For example, technical properties that are derived on the server, are not present in the "create-form" resource because HTTP API ignores them during POST. See Operations Overview and Concepts which properties HTTP API will and will not process during POST.

  2. The properties are returned in their "native" format. This means, a client just can fill in the values and send the payload to HTTP API without the need to make structural changes in the format. The "native" format of each type is documented in Property Representation (GET).

  3. Sub resources are by default not included. They can be included using "expand", see Influence Resource Representation

  4. For linked resources by default the "id" property is used. This cannot be influenced using "fields".

Example of a "create-form" for resource "person" with sub resource "address" included:

{
    "code": "string",
    "dateOfBirth": "1980-12-12",
    "dobInterpretation": "A",
    "gender": "F",
    "name": "string",
    "functionDynamicLogic": {
        "id": 0
    },
    "language": {
        "id": 0
    },
    "addressList": [
        {
            "type": "S",
            "additionalPart1": "string",
            "additionalPart2": "string",
            "additionalPart3": "string",
            "city": "string",
            "endDate": "1980-12-12",
            "houseNumber": 0,
            "numberAddition": 0,
            "postalCode": "string",
            "startDate": "1980-12-12",
            "street": "string",
            "addressAccessRestriction": {
                "id": 0
            },
            "country": {
                "id": 0
            },
            "countryRegion": {
                "id": 0
            }
        }
    ]
}

What to Include

As said in section Property Representation and Handling (PUT, POST, PATCH), clients need not supply values for all properties, they may send in incomplete resource representations.

POST Processing Details

  1. HTTP API is forgiving: when an unknown construct is present in the resource representation, it is ignored. No error is given. This applies to:

    • 1. Unknown properties.

    • 2. Properties that do exists, but cannot be set by a client.

    • 3. Unknown sub resources.

    • 4. Unknown dynamic fields and unknown dynamic records.

  2. HTTP does validate values however for all known constructs. As soon as a property or sub resource if recognized, it’s value is fully validated.

  3. When any validation fails, the whole message is discarded. An error resource is returned as described in the section Operations Overview and Concepts. An HTTP error status code is returned, as described in the section Response Messages

  4. When all validations pass, the resource is created. The newly created resource is returned together with HTTP status code 201.