Common

Introduction

The common specifications are used in both compact and Extended formats.

Global structure

JSON Response body

Form data category

The response body contains a JSON Object per handled resources. That is, the JSON root Object for a single handled resource is a JSON Object as well as for multiple handled resources. The several properties are directly placed into the JSON Object.

• If the insert/update of a single record request or update field in table/dataset request was successful, the code JSON property may be absent and if not, it corresponds to the HTTP response code associated to the handled resource. The validation report is always present. Some properties are optional and added when requested using request parameters. See Form data operations for more information.

  {
    "validation": [
      {
        "level": "error",
        "message": "Field 'Value' is mandatory.",
        "blocksCommit": "never",
        "pathInRecord": "/value"
      },
      {
        "level": "error",
        "message": "Values between 'AD100' and 'AD200' (included) are prohibited.",
        "blocksCommit": "onUserSubmit-checkModifiedValues",
        "pathInRecord": "/code"
      },
      {
        "level": "warning",
        "message": "Value 'AD150' is prohibited.",
        "blocksCommit": "never",
        "pathInRecord": "/code"
      }
    ]
  }

• If the insert multiple record request was successful, the code JSON property may be absent and if not, it corresponds to the HTTP response code associated to the handled resource. The validation report is always present. Some properties are optional and added when requested using request parameters.

  {
    "rows": [
      {
        "label": "My Lable1",
        "details": "http://.../root/table/1",
        "foreignKey": "1",
        "validation": [
          {
            "level": "error",
            "message": "Field 'Value' is mandatory.",
            "blocksCommit": "never",
            "pathInRecord": "/value"
          },
          {
            "level": "error",
            "message": "Values between 'AD100' and 'AD200' (included) are prohibited.",
            "blocksCommit": "onUserSubmit-checkModifiedValues",
            "pathInRecord": "/code"
          },
          {
            "level": "warning",
            "message": "Value 'AD150' is prohibited.",
            "blocksCommit": "never",
            "pathInRecord": "/code"
          }
        ]
      },
      {
        "label": "My Lable2",
        "details": "http://.../root/table/2",
        "foreignKey": "2",
        "validation": [
          {
            "level": "error",
            "message": "Field 'Value' is mandatory.",
            "blocksCommit": "never",
            "pathInRecord": "/value"
          },
          {
            "level": "error",
            "message": "Values between 'AD100' and 'AD200' (included) are prohibited.",
            "blocksCommit": "onUserSubmit-checkModifiedValues",
            "pathInRecord": "/code"
          },
          {
            "level": "warning",
            "message": "Value 'AD150' is prohibited.",
            "blocksCommit": "never",
            "pathInRecord": "/code"
          }
        ]
      }
    ]
  }

• If the insert/update of a single record request or update field in table/dataset failed, the response body corresponds to a JSON Exception handling response.

  {
    "code": 422,
    "errors": [
      {
        "level": "error",
        "userCode": "Validation",
        "message": "Field 'Category' is mandatory.",
        "blocksCommit": "never",
        "pathInRecord": "/category"
      },
      {
        "level": "error",
        "userCode": "Validation",
        "message": "Values between 'AD100' and 'AD200' (included) are prohibited.",
        "blocksCommit": "onUserSubmit-checkModifiedValues",
        "pathInRecord": "/code"
      }
    ]
  }

• If the insert multiple record request failed, the response body corresponds to a JSON Exception handling response.

  {
    "code": 422,
    "errors": [
      {
        "level": "error",
        "rowIndex": 0,
        "userCode": "Validation",
        "message": "Values between 'AD100' and 'AD200' (included) are prohibited.",
        "blocksCommit": "onUserSubmit-checkModifiedValues",
        "pathInRecord": "/code"
      },
      {
        "level": "error",
        "rowIndex": 0,
        "userCode": "Validation",
        "message": "Field 'Value Less Than' is mandatory.",
        "blocksCommit": "never",
        "pathInRecord": "/less_than_value"
      },
      {
        "level": "error",
        "rowIndex": 1,
        "userCode": "Validation",
        "message": "Values between 'AD100' and 'AD200' (included) are prohibited.",
        "blocksCommit": "onUserSubmit-checkModifiedValues",
        "pathInRecord": "/code"
      },
      {
        "level": "error",
        "rowIndex": 1,
        "userCode": "Validation",
        "message": "Field 'Value Less Than' is mandatory.",
        "blocksCommit": "never",
        "pathInRecord": "/less_than_value"
      }
    ]
  }

Form validation report

This report can be retrieve by using the Form data operations. It provides every validation constraint on the requested resource.

Those constraints have the following properties:

(*) Only available for record and record field operations.

(**) Only available for dataset operations.

Content

Pagination

Use pagination to return a limited and parameterizable number of data. Pagination can be applied to the following data types: records, association values, selection node values, selectors, dataspaces and datasets. A context named pagination is always returned. This context allows you to browse data in a similar manner to the UI.

The pagination is always enabled.

The following provides detailed information related to this context:

Content of simple type

Insert operation report

When invoking the insert operation with a record table, it can optionally return a report. The report includes a JSON Object that contains the following properties:

• count contains an int of JSON Number type, that defines the number of processed records since the listed rows can not be exhaustive in several cases.

• isPartialList contains a boolean of JSON Boolean type, that is true if the listed rows are only a partial list of the whole processed records, false otherwise.

• rows contains a JSON Array, where each element corresponds to the result of a request element.

• code contains an int of JSON Number type, and allows to know whether the record has been inserted or updated. This property is included if, and only if, the updateOrInsert parameter is set to true.

• foreignKey contains a string of JSON String type, corresponding to the content to be used as a foreign key for this record. This property is included if, and only if, the parameter includeForeignKey is set to true.

• label contains a string of JSON String type, and allows to retrieve the record label. This property is included if, and only if, the parameter includeLabel is set to yes.

• details containing a string of JSON String type, corresponding to the resource URL. This property is included if, and only if, the parameter includeDetails is set to true.

{
  "count": 2,
  "isPartialList": false,
  "rows": [
    {
      "code": 204,
      "foreignKey": "62",
      "label": "Claude Debussy",
      "details": "http://.../root/individu/62"
    },
    {
      "code": 201,
      "foreignKey": "195",
      "label": "Camille Saint-Saëns",
      "details": "http://.../root/individu/195"
    }
  ]
}

Delete operation report

When invoking the delete operation, a report is returned. The report includes a JSON Object that contains the following properties:

• deletedCount containing an integer of JSON Number type, corresponds to the number of deleted records.

• occultedCount containing an integer of JSON Number type, corresponds to the number of occulted records.

• inheritedCount containing an integer of JSON Number type, corresponds to the number of inherited records.

{
  "deletedCount": 1,
  "inheritedCount": 0,
  "occultedCount": 0
}

Technical data

Each returned record can contain its system records metadata under ebx-metadata/system properties corresponding to the technical data. System metadata are requestable and sortable.

To include records metadata, see includeMetadata=system parameter value for select operation.

For extended format:

{
  ...,
  "ebx-metadata":{
    "content":{
      "system":{
        "content":{
          "uuid":{
            "content":"7FE03810-6A67-11ED-A892-00FF20216100"
          },
          "creator":{
            "content":"Uadmin"
          },
          "creation_time":{
            "content":"2022-11-22T14:13:47.793"
          },
          "updater":{
            "content":"Uadmin"
          },
          "update_time":{
            "content":"2022-11-29T17:46:55.686"
          }
        }
      }
    }
  }
}

For compact format:

{
  ...,
  "ebx-metadata":{
    "system":{
      "uuid":"7FE03810-6A67-11ED-A892-00FF20216100",
      "creator":"Uadmin",
      "creation_time":"2022-11-22T14:13:47.793",
      "updater":"Uadmin",
      "update_time":"2022-11-29T17:46:55.686"
    }
  }
}

Update modes

The byDelta mode allows to ignore data model elements that are missing from the JSON source document. This mode is enabled (by default) through RESTful operations. The following table summarizes the behavior of insert and update operations when elements are not included in the source document.

See the RESTful data services operations update and insert, as well as ImportSpec.setByDelta in the Java API for more information.

Known limitations

Field values

The value of fields xs:date, xs:time and xs:dateTime does not contain a time zone associated with the JSON-primitive type.

Indexing and search strategy

Filterable and sortable values from the metamodel are limited to the default search strategy.