Create Entities
The Entities API lets you create entities by performing a POST
request against the /entities/:entityName
endpoint.
Create an Entity
The request body contains a JSON object with the attributes of the entity.
Attributes from Entity Traits like id or createdBy should not be part of the request. Those attributes are automatically added by Jmix while storing the entity.
|
When the entity is created successfully, the HTTP response status code 201 - Created
is returned. By default, a JSON metadata representation of the entity is returned mainly containing the newly created id
attribute for further reference.
POST http://localhost:8080/rest/entities/sample_Customer
{
name: "Randall Bishop"
}
{
"_entityName": "sample_Customer",
"_instanceName": "Randall Bishop",
"id": "78e7996d-8b69-6526-8e9f-16262a1c4113"
}
Alternatively, it is possible to define which attributes should be returned once the entity is created. This can be achieved through the URL query parameter responseFetchPlan
.
For example, the URL /entities/sample_Order?responseFetchPlan=order-with-details
would return the complete order with all its details containing order lines, customer references etc.
The HTTP response Header Location indicates also the URL to the newly created entity instance for further operations (like fetching, updating, or deleting).
|
Entity Validation
When an entity is created or updated, the regular entity validation is active and enforced by default. This means that invalid input (according to the entity validation annotations) from the API is rejected with the HTTP response status code 400 - Bad Request
.
The API returns detailed error messages for each validation violation in the following form of a JSON array. Each entry follows the structure:
- message
-
the (translated) human-readable error message of the violation
- messageTemplate
-
the non-interpolated error message for this constraint violation
- path
-
the attribute name (or property path) of the attribute that caused the violation
- invalidValue
-
the value that was part of the request for the attribute, which causes the violation
The following request contains two errors in the request, as 1. the customer
attribute is required and 2. the date
should not be in the future.
POST http://localhost:8080/rest/entities/sample_Order
{
"date": "2048-01-01",
"amount": 49.99,
"customer": null
}
The API then returns the list of violations of the entity validations.
[
{
"message": "javax.validation.constraints.PastOrPresent.message",
"messageTemplate": "{javax.validation.constraints.PastOrPresent.message}",
"path": "date",
"invalidValue": "2048-01-01"
},
{
"message": "may not be null",
"messageTemplate": "{javax.validation.constraints.NotNull.message}",
"path": "customer",
"invalidValue": null
}
]
Association Attributes
When the entity to create should be linked to another existing entity, it is required to reference the other entity in the request.
In the Order example, you want to reference a Customer via the customer
attribute when you create the Order. This is done through a JSON object containing only the ID of the existing entity. Jmix performs a lookup of the customer by the provided ID from the JSON request and links the customer to the new order.
POST http://localhost:8080/rest/entities/sample_Order
{
"customer": {
"id": "f88597ff-009d-1cf2-4a90-a4fb5b08d835"
},
"date": "2021-03-01",
"amount": 130.08
}
For all kinds of associations: 1:N
, N:1
, M:N
the way to reference other entities is always via its ID.
The second example shows how to link a Product
to multiple ProductTag
entities via an M:N
relationship, as described in the Product entity definition.
@JmixEntity
@Table(name = "SAMPLE_PRODUCT")
@Entity(name = "sample_Product")
public class Product {
@JoinTable(name = "SAMPLE_PRODUCT_PRODUCT_TAG_LINK",
joinColumns = @JoinColumn(name = "PRODUCT_ID"),
inverseJoinColumns = @JoinColumn(name = "PRODUCT_TAG_ID"))
@ManyToMany
private List<ProductTag> tags;
// ...
}
In the request, the ProductTag
entity instances are references by their ids. This time, the JSON object is put into an array, as there are multiple product tags to reference.
M:N
referencesPOST http://localhost:8080/rest/entities/sample_Product?responseFetchPlan=product-with-tags
{
"name": "123",
"price": 99.95,
"tags": [
{
"id": "333f3a20-c47b-4bc9-ba34-a72d2d815695" (1)
},
{
"id": "c4c028f0-fec1-7512-83cd-c17537d1f502"
}
]
}
{
"id": "f0e04748-dcdf-d856-2482-2904f2126fcc",
"price": 99.95,
"name": "123",
"tags": [
{
"id": "333f3a20-c47b-4bc9-ba34-a72d2d815695", (2)
"name": "shiny"
},
{
"id": "c4c028f0-fec1-7512-83cd-c17537d1f502",
"name": "great"
}
]
}
1 | The tags are referenced as a list of JSON objects containing the ID of the already existing ProductTag . |
2 | The response contains the stored association to the two ProductTag entities. |
Composition Attributes
For attributes that are marked as @Composition
the situation is slightly different. As this relationship type indicates that the child entities only exist as part of the parent entity, it is also possible to directly create child entities as part of the request to create a parent.
In the next example, the OrderLine
entity is a child entity of the Order
entity. This is expressed through the @Composition
annotation on the lines
attribute of the Order
entity.
public class Order {
@JmixGeneratedValue
@Column(name = "ID", nullable = false)
@Id
private UUID id;
@Composition
@OneToMany(mappedBy = "order")
private List<OrderLine> lines;
// ...
}
When you create an order through the API you can directly create its order lines as part of the request. In this case, all the attributes of the child entity need to be provided. The relationship from the parent to the child does not need to be additionally referenced. Putting the child entity into the JSON array is enough to establish the connection.
The following JSON request will create an order with its order lines:
POST http://localhost:8080/rest/entities/sample_Order
{
"customer": {
"id": "f88597ff-009d-1cf2-4a90-a4fb5b08d835"
},
"date": "2021-03-01",
"amount": 130.08,
"lines": [ (1)
{
"quantity": 2,
"product": {
"id": "7750adbe-6c30-cede-31a6-577a1a96aa83" (2)
}
},
{
"quantity": 1,
"product": {
"code": "1ed85c7a-89f1-c339-a738-16307ed6003a"
}
}
]
}
1 | Order lines are created as an array of JSON objects containing all the attributes of the entity. |
2 | In case a child entity needs to reference another entity (like the N:1 reference from the OrderLine to Product ), the same rules of referencing via JSON object containing the ID apply. |
Bulk Creation
The Create-Entity API also allows you to create multiple entities within one request. For this the JSON request body should contain an array of JSON objects representing each entity.
POST http://localhost:8080/rest
/entities
/sample_Customer
[
{
"name": "Randall Bishop"
},
{
"name": "Sarah Doogle"
}
]
[
{
"id": "c5fea05d-9062-6ac8-e9b1-7051616de102"
},
{
"id": "4a6a3aa0-ecf5-dcf4-7b37-a268a4cd3720"
}
]
In case of a violation of an entity validation, the entities will not be created, and a corresponding Error message will be returned. See Entity Validation for further details.