NAV

Preface

Welcome to the d.velop business objects API Guide! You can use the business objects API to create all the calls you need to integrate with d.velop business objects. This guide provides information on available endpoints and how to interact with it.

Version: 1.2.2

Last updated: 2024-02-15

Revision History

Date Version Description
2021-01-19 1.0.0 Initial Revision (Friendly-User-Phase)
2021-05-03 1.0.1 Minor fixes
2021-05-27 1.1.0 New chapters Limits, Versioning, Pagination
2021-12-10 1.1.1 Updated limit values
Structure and formatting slightly revised
2022-09-23 1.2.0 New chapters/sections Batching, Batching limits, Batching example
2023-05-04 1.2.1 Minor corrections and additions in the Batching chapter
2024-02-15 1.2.2 Added new error code

Introduction

The business objects API can be accessed over HTTPS and is based on RESTful design principles and OData V4. We use predictable resource-oriented URLs, accept JSON request bodies and return JSON responses. The only exception to this is our metadata endpoint, which is currently still based on XML. The API uses standard HTTP response codes, authentication, and verbs.

Above all, the self-describing interface of business objects will help you to interact with the service without having to know details about the underlying protocol.

Prerequisites

Before you can use the business objects API within your application, you first have to subscribe and configure the app in your tenant. To register a new tenant or to subscribe the app visit the d.velop cloud center at https://my.d-velop.cloud.

Since all requests to the API must be authenticated, users or API keys must also be configured that have the appropriate authorization.

API Root endpoint

In this documentation, we will use the term Root endpoint to refer to the base address of the business objects service.

Root endpoint https://<tenantDomain>.d-velop.cloud/businessobjects/

Unless stated otherwise, all addresses in the rest of this documentation are relative to the root endpoint.

Making requests

HTTP verbs

As per RESTful design patterns, business objects API uses the following HTTP verbs that most clients are familiar with:

PATCH is recommended as the preferred means of updating an entity.

Request Format

For POST, PUT, and PATCH requests, the request body is OData flavored JSON (the Content-Type header must be set to application/json).

Response Format

The default response format is OData flavored JSON (except where noted), encoded in the UTF-8 character encoding.

Security

Requests must be made over HTTPS. Any non-secure requests are met with a redirect to the HTTPS equivalent URI. Make sure that your application validates certificates.

Authentication

Only authenticated users are allowed to make API requests. So using the service requires a valid authentication of the Identity Provider App.

See Identity Provider App documentation for a detailed overview about the authentication and authorization process, on how to get such authentication and how to implement it in your application.

The AuthSessionId must be given to every request. This can be done in two ways:

Which variant should be used depends on your requirements. If business objects is accessed from a browser, the use of cookies is more advisable. For server-to-server communication, a bearer token is usually the preferred way.

Bearer

An authorization header containing a valid bearer token can be included in a request like follows:

Authorization: Bearer <bearerToken>

You must replace <bearer_token> with your personal bearer token. It is base64 encoded and usually looks something like cF9/EIVw....

Cookies are handled automatically in the browser. If you still have to create and transfer the cookie manually, make sure that the AuthSessionId has to be URL-encoded.

Altering the state of the server

In the case of HTTP methods that change the server-side state (POST, PUT, PATCH, and DELETE), the Origin header must be transferred and must match the target origin. Otherwise the request is rejected with the status code 403 Forbidden. The Origin request header indicates where a fetch originates from and must be set as follows:

Origin: <baseURI>

Set the baseURI variable to a valid value for your tenant. The format for this is: https://<tenantDomain>.d-velop.cloud (the header does not contain any path information).

Application Roles

The following roles are used by business objects:

Role Permissions Description
Tenant Admin All application permissions Predefined administration role with tenant wide permissions
Manage models Read and write (create, read, update, delete) custom models Administration of the model configuration
Deliver data Write instance data (create, update, delete) Usually, for technical users who need write access to the instance data
Query data Read instance data Typically assigned to technical users who need read access to the instance data

Status codes and errors

business objects uses conventional HTTP status codes that most clients are familiar with to indicate the success or failure of an request:

Frequently used HTTP status codes

The following is a list of common HTTP status codes you see in response from the API and what they mean. Details on error handling for the individual resources can be found in the respective section.

HTTP Status Code Description
200 OK Everything worked as expected and the response body contains the representation requested.
201 Created The request was successful, a new resource was created and the response body contains an unexpanded representation of the created resource. The location of the newly created resource can be found in the Location header.
204 No Content Everything worked as expected and the response body is empty.
400 Bad Request The request contains syntactic or semantic errors. The response body contains further error details that the client can use to troubleshoot the problem.
401 Unauthorized The request couldn't be authenticated.
403 Forbidden The client doesn't have permissions to perform the request.
404 Not Found The requested resource could not be found.
409 Conflict The requested operation on the resource cannot be performed due to the resource status.
413 Request Entity Too Large The request body is larger than the defined limits.
414 URI Too Long The URI requested is longer than the defined limits.
415 Unsupported Media Type The request was rejected because the payload format is not supported.
429 Too Many Requests Too many requests have been sent in a given amount of time.
431 Request Header Fields Too Large The request's HTTP headers are too long.
500 Internal Server Error There was a technical problem with the API server.
501 Not Implemented The functionality required to fulfill the request is not supported.
503 Service Unavailable The connection is being throttled or the service is temporarily offline for maintenance.

Errors

If an error occurs, the response contains an HTTP status code and usually also a response body with an error code and a message. The error codes are machine-readable codes that allow clients to better understand the context of the error and respond appropriately. The message includes a user-friendly explanation of the error.

Error Schema

errorResponse

Represents an error response object.

Name Type Nullable Description
error errorContainer false The actual error payload.

errorContainer

Represents an error container encompassing the error payload.

Name Type Nullable Description
code string false A service-defined error code.
message string false A human-readable representation of the error.
details errorDetail[] true A collection of error details.
innerError innerError true Debugging information to help determine the error cause.

errorDetail

Represents an error detail.

Name Type Nullable Description
code string false An error detail code defined by the service.
message string false A human-readable representation of the error detail.

innerError

Represents an error object with debugging information to help determine the error cause.

Name Type Nullable Description
timestamp string true The timestamp as the error occurred.
requestId string true A randomly generated identifier that uniquely distinguishes each request and that can be used for correlation purposes.

Error codes

Code Description
badValue A bad value was found while executing the query.
contentTypeNotSupported The given content type does not match a supported MIME type.
divisionByZero A division by zero error occurred while executing the query.
entityAlreadyExists The entity already exists.
entityNotFound The requested entity could not be found.
entityUnknown One or more of the specified entity keys are unknown.
featureForbidden The specified feature is forbidden. The error message contains information about the forbidden feature.
featureNotImplemented The specified feature is not implemented. The error message describes the functionality not implemented.
limitExceeded A limit has been exceeded.
methodNotAllowed The target resource doesn't support the specified method.
moduloByZero A modulo by zero error occurred while executing the query.
notDeletable The specified element is not deletable.
notInsertable The specified element is not insertable.
notUpdatable The specified element is not updatable.
payloadTooLarge The given request payload is larger than the limits defined by the service.
queryMalformed The query is either syntactically or semantically malformed.
requestEntityMalformed The request body is either syntactically or semantically malformed.
resourceNotFound The requested resource could not be found.
tooManyRequests Too many requests were sent in a given amount of time.
transitionInvalid The specified transition is invalid.
writeConflict There was a conflict while attempting to write the entity.

Limits

business objects implements a number of safeguards against excessive use of the service, whether that excessive use is intentional or unintentional. The so-called soft limits are an essential part of these safeguards. They limit the resource usage and protect the underlying services and resources and are enforced by business objects. They help to maintain the availability and performance and to maximize the stability of the service.

For some limits you can apply for a limit increase, while other limits cannot be increased. This depends on your specific use case and the selected integration approach. Contact the business objects support if you want to apply for a limit increase or if you have any questions about this.

HTTP request limits

Constraints and limits relating to the HTTP protocol. Please note that further restrictions may apply which are specified and enforced by the d.velop cloud infrastructure and which may come into effect beforehand.

Id Resource Limit
requestBodyMaxSize Maximum allowed size of any request body 800 kB
requestLineMaxSize Maximum allowed size for the HTTP request line/request URL 4096 bytes
requestHeaderMaxCount Maximum allowed number of headers (key/value) per HTTP request 50 headers
requestHeadersTotalMaxSize Maximum allowed total size for the HTTP request headers 8192 bytes

Data type limits

Restrictions and limits related to the data types that can be used in business objects

Id Resource Limit
keyMaxLength Maximum allowed length for a primary key with an otherwise unrestricted property type (e.g. string) 256 chars/bytes
propertyValueMaxLength Maximum allowed length for a property with an otherwise unrestricted property type (e.g. string or binary) 2000 chars/bytes
listMaxLength Maximum number of items allowed for a list property 200
listItemMaxLength Maximum length allowed for an item of a list property with an otherwise unrestricted item type (e.g. string) 400 chars/bytes

Custom model configuration limits

Limits that apply when modeling custom models

Id Resource Limit
modelMaxCount Maximum allowed number of custom models per tenant 5
entityTypesMaxCount Maximum allowed number of entity types per custom model 10
propertiesMaxCount Maximum allowed number of properties (including key property) per entity type 60
indexedPropertiesMaxCount Maximum allowed number of indexed properties (secondary indexes) per entity type 5

Storage limits for core entities

Quotas and limits for the permanent storage of core entities

Id Resource Limit
coreEntityMaxSize Maximum allowed size for an instance of a core entity type (e.g. a custom model aggregate) 40000 bytes

Storage limits for custom entities

Quotas and limits for the permanent storage of custom entities

Id Resource Limit
entityMaxSize Maximum allowed size for an instance of a custom entity type 4000 bytes
entitiesMaxCount Maximum allowed number of entities/instances per entity type 100000
entitiesMaxSize Maximum allowed size for instances per entity type 200 MB
entitiesTotalMaxCount Maximum allowed number of entities/instances per tenant 500000
entitiesTotalMaxSize Maximum allowed total size for instances per tenant 1 GB

Enforcing the limits (preview)

If one of the data storage limits entitiesMaxCount, entitiesMaxSize, entitiesTotalMaxCount, and entitiesTotalMaxSize has been exceeded for more than 5 days, the creation and modification of entities will be rejected. Getting entities remains possible, as does deleting entities to reduce current data storage. Details can be found in the following table:

Request type Rejected
GET No
DELETE No
POST, PUT, PATCH Yes
DELETE in batch No
POST, PUT in batch Yes

After the current data storage has been reduced, the service can be used again without restrictions.

Query and retrieval limits

Limits that apply when querying and retrieving objects

Id Resource Limit
pageSize Maximum allowed number of returned objects in a paginated result 100

Batching limits

Limits that apply to the batching interface

Id Resource Limit
maxRequestsPerBatch Maximum allowed requests within a batch request 100
maxBatchPayload Maximum allowed size of a batch request payload 800 kB

Rate limits (preview)

In order to maximize service availability and performance, a number of protective measures against incoming requests have been implemented. Clients who send many requests in quick succession may receive error responses with a status code of 429 Too Many Requests.

You should always look for ways to reduce the number of requests and you must make sure you have rate limit handling in place to process such responses and try again in a reasonable time.

Response headers

To help you with this handling, each request to a rate limited resource contains response headers that reflect the current status of the rate limit (for exceptions to this, see below).

Header Description
X-RateLimit-Limit Indicates the request quota and the associated time window.
X-RateLimit-Remaining The number of requests remaining in the current rate limit window. Only included when the rate limit is not exceeded.
Retry-After Indicates the seconds to wait before making a follow-up request. Only sent when the rate limit is exceeded.

Handling rate limits

The pre-determined rate limits are listed in the following table. Currently, a distinction is made between read (HTTP method GET) and write access (HTTP methods POST, PUT, PATCH, DELETE). The mentioned time windows are to be understood as sliding time windows that move forward with each request.

Request type / Time window 2s 3600s
GET 40 N/A
POST, PUT, PATCH, DELETE 30 5000

These limits apply per tenant and are subject to change. If more than one client accesses a tenant, the clients are responsible for dividing the available request quotas appropriately.

The limit values are to be understood as maximum values. The highest data throughput is achieved by controlling the request rate on the client side and ensuring there that the rate limits are not exceeded (restricting the rate and allowed parallel executions of API calls).

If a request has been throttled, the client must wait at least the time specified in the HTTP response header Retry-After before the request is sent again.

Errors of the type 429 Too Many Requests can be received even if the above limits are not reached. This can happen, for example, in situations in which the services are under heavy load. In these cases, the above response headers are optional.

Usage policy

In addition to the aforementioned usage limits, you must ensure that you are using business objects features within the business objects terms of use. For more information on this terms, see the business objects product terms.

Versioning

business objects implements a versioning approach that allows us to continue developing new features and improvements while providing a stable API behavior and predictable timelines for adopting changes.

We intend to release major versions as needed and no more frequently than every 12 months. A major release is released when breaking changes are introduced to the API. These usually require development efforts to adapt the client code to preserve existing application functionality. To facilitate the necessary transition, we will publish migration guides whenever we release a new major version.

Non-breaking or backward-compatible changes are additive and will be included in as a minor release in the current version as they are completed. They do not require any adjustments on the part of the developers unless they want to integrate the new functionality.

We follow the versioning principles explained here for all components of business objects, both for the core resources of the metamodel and for the custom models themselves. Details on how these principles are implemented in modeling can be found in the corresponding section.

Versioning schema

We follow the semantics of version information as described in Semantic Versioning. The version number format we use is:

Version number format <MAJOR>.<MINOR>.<PATCH>+<BUILD>

According to Semantic Versioning rules, we

Only when versioning the app as a whole we use the build metadata label BUILD. Data models and schemas are only versioned according to the simplified versioning scheme consisting of MAJOR.MINOR.PATCH.

Also, we do not currently use the pre-release labels (as optional with Semantic Versioning), but may do so in the future.

Non-breaking or backwards-compatible changes

The following changes are considered non-breaking or backward-compatible (among others):

Breaking or incompatible changes

Incompatible changes that require changes to the client code to maintain existing functionality include the following changes (examples):

Pagination

Most of the business objects API resources support bulk fetches. If the result set exceeds a certain size, not all items are returned at once, but rather it is split across multiple data pages using server-side paging. In this way, clients can load large amounts of data incrementally and quickly. This helps keeping response times short and user experience high.

Whenever a client requests a collection of entities and the result set exceeds the default page size, the response will contain a partial result and an additional @odata.nextLink annotation. The annotation contains a URL that can be used to obtain further results and looks similar to the following.

"@odata.nextLink": "https://.../businessobjects/custom/examples?$skiptoken=..."

The next page of results can be obtained by requesting the URL, and each subsequent response will in turn contain a link to the next page of data until all of the pages in the result set have been obtained.

Batching

business objects allows grouping multiple individual requests into a single batch request using the OData JSON Batch Format as defined in OData JSON Format. Using batch bulk operations reduces the number of round trips to the service and avoids the cost of network latency per request.

Individual requests within a batch request are executed using the same interaction semantics used when the request is executed outside of the context of a batch request.

Batching is only supported for custom entity types that have been published. Neither dependent requests nor atomic groups are currently supported. Individual requests may be processed in parallel and in any order.

Batch processing in a nutshell

Batch requests

A batch request is sent as a single POST request to a batch endpoint of a custom data service, located at the URL$batch relative to the custom data service root, such as https://<tenantDomain>.d-velop.cloud/businessobjects/custom/example/$batch. The request containing the batch must have a Content-Type header with a value set to application/json.

Submitting a batch request

POST /businessobjects/custom/example/$batch HTTP/1.1
Host: <tenantDomain>.d-velop.cloud
Authorization: Bearer <bearerToken>
Content-Type: application/json

The request body consists of an object with the attribute requests containing an array of individual requests.

Example batch request bodies (mixing different methods in a single batch request is not supported)

// Create entities
{
  "requests": [{
    "id": "1",
    "method": "POST",
    "url": "customers",
    "headers": {
      "content-type": "application/json"
    },
    "body": {
      /* new customer JSON */
    }
  }, {
    "id": "2",
    "method": "POST",
    "url": "customers",
    "headers": {
      "content-type": "application/json"
    },
    "body": {
      /* new customer JSON */
    }
  }]
}
// Update entities
{
  "requests": [{
    "id": "1",
    "method": "PUT",
    "url": "customers(f735a0bd-3342-46a7-9db3-eea9a41cda3d)",
    "headers": {
      "content-type": "application/json"
    },
    "body": {
      /* replacing customer JSON */
    }
  },
  {
    "id": "2",
    "method": "PUT",
    "url": "customers(7d6374bf-3721-4577-872c-73109642fedc)",
    "headers": {
      "content-type": "application/json"
    },
    "body": {
      /* replacing customer JSON */
    }
  }]
}
// Delete entities
{
  "requests": [{
    "id": "1",
    "method": "DELETE",
    "url": "customers(f735a0bd-3342-46a7-9db3-eea9a41cda3d)"
  },
  {
    "id": "2",
    "method": "DELETE",
    "url": "customers(7d6374bf-3721-4577-872c-73109642fedc)"
  }]
}

Each individual request must contain at least the properties id, method and url. Currently, business objects allows the following methods for individual requests within a batch request:

Attribute Required Description
id Always A string containing a unique identifier for the request. It must match the regular expression [a-z0-9_-]{1,50}
method Always One of POST, PUT, DELETE as described above
url Always The relative path to the entity set or entity, for POST in the format <plural name> and for PUT and DELETE in the format <plural name>(<primary key>)
headers Conditional Required, if a body is specified. If so, it must include a Content-Type header with the value application/json
body Conditional The payload holding the values for an entity, required for POST and PUT requests

Batch responses

If the batch is unprocessable, e.g. due to syntax errors in the batch envelope, it fails completely and returns an error status code. A single error response object is returned which contains more detailed information about the cause.

Otherwise the service returns HTTP status code 200 OK and a batch response similar to the batch request that contains the responses to each of the individual requests. The response format for batch requests consists of an object containing a top level attribute named responses, whose value is an array carrying individual responses related to the individual requests of the batch request.

Receiving a batch response

HTTP/1.1 200 OK
Content-Type: application/json

Example batch response body

{
  "responses": [{
    "id": "1",
    "status": 201,
    "headers": {
      /* response headers */
    },
    "body": {
      /* created customer JSON */
    }
  },
  {
    "id": "2",
    "status": 400,
    "headers": {
      /* response headers */
    },
    "body": { 
      "error": {
        /* error details JSON */
      }
    }
  }]
}

Each individual response contains at least the properties id and status.

Attribute Description
id The unique identifier of the corresponding request
status The HTTP status code of the response to the individual request (see Frequently used HTTP status codes)
headers An object with name/value pairs representing response headers
body Depending on the request and the result, a representation of the newly created entity or an error object with more detailed information about the error

The body is provided as follows:

Differences compared to individual processing

In contrast to single processing, there are the following differences:

In both cases, the other request validation remains unaffected, e.g. syntactically invalid requests are answered with a 4xx error as usual.

We will align single processing with batch processing in this regard. Since this means a breaking change, we will announce this beforehand and allow sufficient time for the necessary adjustments.

Limitations

business objects doesn't currently support the OData Batching features listed below:

Feature
Partial updates via PATCH
Using GET to retrieve data
Mixing different methods in a batch request
Using different entity types in a batch request
Multipart Batch Format
Using atomic groups (atomicGroup)
Using dependent requests (dependsOn)
Using absolute paths and absolute URLs in url attribute
Asynchronous batch requests
Support continue-on-error=false in Prefer header value
Using key as segment convention in url
Referencing new entities with variables $<...> in url and headers
Support instance annotations/context control information in request bodies

Models

customModels

List all custom models

GET core/models/customModels

Retrieves all custom models.

Success Response

{
  "value": [{
    "id": "a2ba1abe-b708-43fe-bd59-c54c4940000f",
    "name": "example1",
    "description": "First example",
    "state": "staged"
  },{
    "id": "83e56be3-e1dd-4641-babc-54a8e358a928",
    "name": "example2",
    "description": "Second example",
    "state": "published"
  }]
}

Success Response

A successful response will have a 200 OK HTTP status code and, for example, the following response body:

Create a new custom model

POST core/models/customModels

Creates a new custom model.

Request Body

{
  "name": "example",
  "description": "A sample service for d.velop business objects",
  "state": "initial"
}

Success Response

{
  "id": "5d9aa2ef-397c-4bf1-b6ec-32e60bc3653e",
  "name": "example",
  "description": "A sample service for d.velop business objects",
  "state": "initial"
}

Success Response

A successful response will have a 201 Created HTTP status code and, for example, the following response body:

Get custom model details

GET core/models/customModels({cmId})

Retrieves the information of the given custom model.

Parameters

Parameter In Type Required Description
cmId Path string true The unique identifier of the custom model.

Success Response

{
  "id": "5d9aa2ef-397c-4bf1-b6ec-32e60bc3653e",
  "name": "example",
  "description": "A sample service for d.velop business objects",
  "state": "initial"
}

Success Response

A successful response will have a 200 OK HTTP status code and, for example, the following response body:

Partially update a custom model

PATCH core/models/customModels({cmId})

Updates an existing custom model partially.

Parameters

Parameter In Type Required Description
cmId Path string true The unique identifier of the custom model.

Request Body

{
  "description": "Partially updating a custom model"
}

Success Response

A successful response will have a 204 No Content HTTP status code and will have no response body.

Replace a custom model

PUT core/models/customModels({cmId})

Replaces an existing custom model.

Parameters

Parameter In Type Required Description
cmId Path string true The unique identifier of the custom model.

Request Body

{
  "name": "api_documentation_replaced",
  "description": "Replacing a custom model"
}

Success Response

A successful response will have a 204 No Content HTTP status code and will have no response body.

Delete a custom model

DELETE core/models/customModels({cmId})

Delete an existing custom model.

Parameters

Parameter In Type Required Description
cmId Path string true The unique identifier of the custom model.

Success Response

{
  "id": "5d9aa2ef-397c-4bf1-b6ec-32e60bc3653e",
  "name": "example",
  "description": "A sample service for d.velop business objects",
  "state": "initial"
}

Success Response

A successful response will have a 200 OK HTTP status code and, for example, the following response body:

entityTypes

List all entity types

GET core/models/customModels({cmId})/entityTypes

Retrieves all entity types.

Parameters

Parameter In Type Required Description
cmId Path string true The unique identifier of the custom model.

Success Response

{
  "value": [{
    "id": "c30c860b-ce22-4374-9796-cec16b6fedc6",
    "name": "invoice",
    "pluralName": "invoices",
    "key": {
      "id": "67593121-e653-4875-a83d-f7aa5b4074fc",
      "name": "id",
      "type": "guid"
    }
  },{
    "id": "ed18e695-8ae4-4203-b0fd-529d1e25b5af",
    "name": "product",
    "pluralName": "products",
    "key": {
      "id": "fa49704f-9c09-47c6-8dcc-f4b2985317e0",
      "name": "id",
      "type": "guid"
    }
  }]
}

Success Response

A successful response will have a 200 OK HTTP status code and, for example, the following response body:

Create a new entity type

POST core/models/customModels({cmId})/entityTypes

Creates a new entity type.

Parameters

Parameter In Type Required Description
cmId Path string true The unique identifier of the custom model.

Request Body

{
  "name": "customer",
  "pluralName": "customers",
  "key": {
    "name": "id",
    "type": "guid",
    "description": "Unique identifier of the customer"
  },
  "description": "A simple customer schema as an example"
}

Success Response

{
  "name": "customer",
  "pluralName": "customers",
  "description": "A simple customer schema as an example"
}

Success Response

A successful response will have a 201 Created HTTP status code and, for example, the following response body:

Get entity type details

GET core/models/customModels({cmId})/entityTypes({etId})

Retrieves the information of the given entity type.

Parameters

Parameter In Type Required Description
cmId Path string true The unique identifier of the custom model.
etId Path string true The unique identifier of the entity type.

Success Response

{
  "id": "8de50cbc-3693-4406-ad1b-feda454230e2",
  "name": "customer",
  "pluralName": "customers",
  "description": "A simple customer schema as an example"
}

Success Response

A successful response will have a 200 OK HTTP status code and, for example, the following response body:

Partially update a entity type

PATCH core/models/customModels({cmId})/entityTypes({etId})

Updates an existing entity type partially.

Parameters

Parameter In Type Required Description
cmId Path string true The unique identifier of the custom model.
etId Path string true The unique identifier of the entity type.

Request Body

{
  "description": "Partially updating an entity type"
}

Success Response

A successful response will have a 204 No Content HTTP status code and will have no response body.

Replace a entity type

PUT core/models/customModels({cmId})/entityTypes({etId})

Replaces an existing entity type.

Parameters

Parameter In Type Required Description
cmId Path string true The unique identifier of the custom model.
etId Path string true The unique identifier of the entity type.

Request Body

{
  "name": "TestCustomer",
  "pluralName": "TestCustomers",
  "description": "Replacing an entity type"
}

Success Response

A successful response will have a 204 No Content HTTP status code and will have no response body.

Delete a entity type

DELETE core/models/customModels({cmId})/entityTypes({etId})

Delete an existing entity type.

Parameters

Parameter In Type Required Description
cmId Path string true The unique identifier of the custom model.
etId Path string true The unique identifier of the entity type.

Success Response

{
  "name": "customer",
  "pluralName": "customers",
  "description": "A simple customer schema as an example"
}

Success Response

A successful response will have a 200 OK HTTP status code and, for example, the following response body:

properties

List all properties

GET core/models/customModels({cmId})/entityTypes({etId})/properties

Retrieves all properties.

Parameters

Parameter In Type Required Description
cmId Path string true The unique identifier of the custom model.
etId Path string true The unique identifier of the entity type.

Success Response

{
  "value": [{
    "id": "1ce177c2-ae1f-491a-9d32-0bd865d69bca",
    "name": "rating",
    "type": "decimal"
  },{
    "id": "9a4e688a-6cdf-4fed-ae82-9ecf54f410a3",
    "name": "code",
    "type": "int16"
  }]
}

Success Response

A successful response will have a 200 OK HTTP status code and, for example, the following response body:

Create a new property

POST core/models/customModels({cmId})/entityTypes({etId})/properties

Creates a new property.

Parameters

Parameter In Type Required Description
cmId Path string true The unique identifier of the custom model.
etId Path string true The unique identifier of the entity type.

Request Body

{
  "name": "name",
  "type": "string",
  "description": "Name of the customer"
}

Success Response

{
  "id": "20936473-f703-45b0-9305-be5066c94f15",
  "name": "name",
  "type": "string",
  "description": "Name of the customer"
}

Success Response

A successful response will have a 201 Created HTTP status code and, for example, the following response body:

Get property details

GET core/models/customModels({cmId})/entityTypes({etId})/properties({pId})

Retrieves the information of the given property.

Parameters

Parameter In Type Required Description
cmId Path string true The unique identifier of the custom model.
etId Path string true The unique identifier of the entity type.
pId Path string true The unique identifier of the property.

Success Response

{
  "id": "20936473-f703-45b0-9305-be5066c94f15",
  "name": "name",
  "type": "string",
  "description": "Name of the customer"
}

Success Response

A successful response will have a 200 OK HTTP status code and, for example, the following response body:

Partially update a property

PATCH core/models/customModels({cmId})/entityTypes({etId})/properties({pId})

Updates an existing property partially.

Parameters

Parameter In Type Required Description
cmId Path string true The unique identifier of the custom model.
etId Path string true The unique identifier of the entity type.
pId Path string true The unique identifier of the property.

Request Body

{
  "description": "Partially updating a property type"
}

Success Response

A successful response will have a 204 No Content HTTP status code and will have no response body.

Replace a property

PUT core/models/customModels({cmId})/entityTypes({etId})/properties({pId})

Replaces an existing property.

Parameters

Parameter In Type Required Description
cmId Path string true The unique identifier of the custom model.
etId Path string true The unique identifier of the entity type.
pId Path string true The unique identifier of the property.

Request Body

{
  "name": "TestName",
  "type": "string",
  "description": "Replacing a property"
}

Success Response

A successful response will have a 204 No Content HTTP status code and will have no response body.

Delete a property

DELETE core/models/customModels({cmId})/entityTypes({etId})/properties({pId})

Delete an existing property.

Parameters

Parameter In Type Required Description
cmId Path string true The unique identifier of the custom model.
etId Path string true The unique identifier of the entity type.
pId Path string true The unique identifier of the property.

Success Response

{
  "id": "20936473-f703-45b0-9305-be5066c94f15",
  "name": "name",
  "type": "string",
  "description": "Name of the customer"
}

Success Response

A successful response will have a 200 OK HTTP status code and, for example, the following response body:

Models Schema

customModel

A user-defined data model, that arranges data elements and covers the relationship of these elements to one another and to entities of reality.

Name Type Nullable Description
id string (uuid) false The unique identifier of the custom model (generated by the service).
name string false The name of the custom model. It serves as part of the service root URL under which the entities are available and must be unique.
description string true An arbitrary string attached to the custom model. Often useful for displaying it to users.
state stateType true The current state of this custom model (default: initial).
entityTypes entityType[] false The entity types of the custom model.

entityType

An entity is not determined by properties, but by an identity. For example, a person is usually represented as an entity.

Name Type Nullable Description
id string (uuid) false The unique identifier of the entity type (generated by the service).
name string false The name of the entity type. It must be unique within the custom model.
pluralName string false The plural name of the entity type. It serves as the entity set (resource) part of the URL under which the entities are available and must be unique within the custom model.
description string true An arbitrary string attached to the entity type. Often useful for displaying it to users.
state stateType true The current state of this entity type. It is derived from the state of the custom model. This property is read-only.
key key false The primary key of the entity type. It is used to uniquely identify instances of this entity type.
properties property[] false The properties of the entity type.

key

A key property is a unique identifier for clear identification of an entity. In principle, identifiers can be used to identify any objects from products to people to abstract concepts.

Name Type Nullable Description
id string (uuid) false The unique identifier of the key property (generated by the service).
name string false The name of the key property. Together with the name of all other properties, it must be unique within the entity type.
description string true An arbitrary string attached to the key property. Often useful for displaying it to users.
type keyType true The type of the key property. It specifies the range of values for the key property and thus defines how an entity is uniquely identified.
state stateType true The current state of this key property. It is derived from the state of the custom model. This property is read-only.

property

Each entity type in a model has a set of properties. It is these properties that are typically of interest for the further use and processing of an entity.

Name Type Nullable Description
id string (uuid) false The unique identifier of the property (generated by the service).
name string false The name of the property. Together with the name of the key property, it must be unique within the entity type.
required boolean true Determines whether the property is an required property.
indexed boolean true Determines whether the property is an indexed property.
description string true An arbitrary string attached to the property. Often useful for displaying it to users.
type propertyType true The type of the property. It determines the kind and range of values the property can store.
state stateType true The current state of this property. It is derived from the state of the custom model. This property is read-only.

keyType

An enumeration type that contains the values that specify the key type.

Name Description
guid A 16-byte (128-bit) unique identifier
int32 A signed 32-bit integer
int64 A signed 64-bit integer
string A sequence of UTF-8 characters

propertyType

An enumeration type that contains the values that specify a property type.

Name Description
binary Binary data
boolean A binary-valued logic value
byte An unsigned 8-bit integer
dateTimeOffset A date and time value with a fixed time-zone offset of +00:00
decimal A numeric value with fixed precision and scale
double An IEEE 754 binary64 floating-point number
guid A 16-byte (128-bit) unique identifier
int16 A signed 16-bit integer
int32 A signed 32-bit integer
int64 A signed 64-bit integer
sByte A signed 8-bit integer
single An IEEE 754 binary32 floating-point number
string A sequence of UTF-8 characters
date A date value
list<string> A list of strings

stateType

An enumeration type that contains the values of different states that a state aware model element can have.

Name Description
initial The model element has an initial status and is a draft. This is the default value when creating the model element.
staged The model element is staged. All instance data of the model element are kept in an intermediate storage area.
published The model element is publicly available to end users and all instance data of the model element are kept in the production storage area.

Example

customers

List all customers

GET custom/example/customers

Retrieves all customers.

Success Response

{
  "value": [{
    "id": "49e086ee-d77e-4009-9332-bfc167e3632c",
    "name": "Linda Lindbergh"
  },{
    "id": "43e07423-d04a-4624-add9-126390b73f56",
    "name": "Bill Burr"
  }]
}

Success Response

A successful response will have a 200 OK HTTP status code and, for example, the following response body:

Create a new customer

POST custom/example/customers

Creates a new customer.

Request Body

{
  "id": "916e6a4b-3fe2-4801-bc8d-b6aa3dfe970c",
  "name": "Jack Jones"
}

Success Response

{
  "id": "916e6a4b-3fe2-4801-bc8d-b6aa3dfe970c",
  "name": "Jack Jones"
}

Success Response

A successful response will have a 201 Created HTTP status code and, for example, the following response body:

Get customer details

GET custom/example/customers({cId})

Retrieves the information of the given customer.

Parameters

Parameter In Type Required Description
cId Path string true The unique identifier of the customer.

Success Response

{
  "id": "916e6a4b-3fe2-4801-bc8d-b6aa3dfe970c",
  "name": "Jack Jones"
}

Success Response

A successful response will have a 200 OK HTTP status code and, for example, the following response body:

Partially update a customer

PATCH custom/example/customers({cId})

Updates an existing customer partially.

Parameters

Parameter In Type Required Description
cId Path string true The unique identifier of the customer.

Request Body

{
  "name": "Jack J. Jones"
}

Success Response

A successful response will have a 204 No Content HTTP status code and will have no response body.

Replace a customer

PUT custom/example/customers({cId})

Replaces an existing customer.

Parameters

Parameter In Type Required Description
cId Path string true The unique identifier of the customer.

Request Body

{
  "id": "916e6a4b-3fe2-4801-bc8d-b6aa3dfe970c",
  "name": "Jack Jones"
}

Success Response

A successful response will have a 204 No Content HTTP status code and will have no response body.

Delete a customer

DELETE custom/example/customers({cId})

Delete an existing customer.

Parameters

Parameter In Type Required Description
cId Path string true The unique identifier of the customer.

Success Response

{
  "id": "916e6a4b-3fe2-4801-bc8d-b6aa3dfe970c",
  "name": "Jack Jones"
}

Success Response

A successful response will have a 200 OK HTTP status code and, for example, the following response body:

Batch customers

POST custom/example/$batch

Batches customer instances.

Request Body

{
  "requests": [{
    "id": "1",
    "method": "POST",
    "url": "customers",
    "body": {
      "id": "49e086ee-d77e-4009-9332-bfc167e3632c",
      "name": "Linda Lindbergh"
    }
  }]
}

Success Response

{
  "responses": [{
    "id": "1",
    "status": "201",
    "headers": {
      "location": "https://…/custom/example/customers(49e086ee-d77e-4009-9332-bfc167e3632c)"
    },
    "body": {
      "id": "49e086ee-d77e-4009-9332-bfc167e3632c",
      "name": "Linda Lindbergh"
    }
  }]
}

Success Response

A successful response will have a 200 OK HTTP status code and, for example, the following response body:

Example Schema

customer

A simple customer schema as an example

Name Type Nullable Description
id string (uuid) false Unique identifier of the customer
name string true Name of the customer