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:
GET
- Read resourcesPOST
- Create new resourcesPUT
- Replace existing resourcesPATCH
- Update parts of resourcesDELETE
- Remove resources
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:
- using the
Authorization
header with theBearer
scheme and a bearer token - or via a cookie
AuthSessionID
that contains the session id
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...
.
Cookie
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:
2xx
- Indicate success4xx
- Indicate failure, the cause of the failure resulted from the provided information and typically lies in responsibility of the client5xx
- Indicate errors that occurred on our servers
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
- increase the
MAJOR
version when we make incompatible (breaking) changes, - increase the
MINOR
version when we add new features that are backward-compatible (non-breaking), and - increase the
PATCH
version if necessary when we make backward compatible bug fixes or editorial changes that do not affect functionality.
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):
- Adding new optional request parameters to existing operations
- Reordering of properties in existing responses
- Addition of a new endpoint or a resource
- Adding new properties to existing responses
- Changing descriptions and error messages
- Adding new types or schemas
Breaking or incompatible changes
Incompatible changes that require changes to the client code to maintain existing functionality include the following changes (examples):
- Renaming or removing properties
- Changing the name of a resource
- Adding required parameters
- Changing a response code or error code
- Removal of an existing endpoint
- Changing the data type of a property
- Removing a query parameter
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.
Navigating through the pages
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:
POST
- Create new entitiesPUT
- Replace existing entitiesDELETE
- Remove entities
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:
- When a client error occured (
status
is in the4xx
range), it may contain further information on the error (see Error Schema) - If an entity creation was requested and successful (
status
is201
), it will contain a representation of the entity created - Successfully replacing (
PUT
) or deleting (DELETE
) an entity does not return a body (status
code204
)
Differences compared to individual processing
In contrast to single processing, there are the following differences:
DELETE
requests are always answered with204
for efficiency and idempotence reasons, regardless of whether the specified entity was deleted within the batch, has already been deleted before, or has ever existed.PUT
requests are interpreted as upserts, meaning they update an existing entity if it already exists and insert a new entity if it doesn't exist.
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 |