. . .

Data oriented content

This page is an in-depth guide about the generated content and behavior of services based on ApiOmat data types. Before going through this guide, you will need to know about the logic flow and the general service architecture.


ApiOmat data types conversion

As you already know, each of the data models you created for your service via the Dashboard can hold attributes. There are multiple data types available for said attributes, as you can see e.g. in the data editor type dropdown within the Grocery class of TutorialService:

images/download/thumbnails/71325462/Screen-Shot-2020-03-11-at-17.05.02.png

When you download your service, each of your data models will have a generated POJO class in the model package, holding the modeled attributes. Each type will correspond to a specific Java type within your data model POJO. Here is the exhaustive list of all types that you can select from the ApiOmat Dashboard and their corresponding Java types:

ApiOmat type

Generated Java type

Description

String

String

Plain text content.

String[ ]

List<String>

List of plain text contents.

Double

Double

Double numeric value.

Double[ ]

List<Double>

List of Double numeric values.

Long

Long

Long numeric value.

Long[ ]

List<Long>

List of Long numeric values.

Date

Instant

Time value corresponding to a specific instant.

Date[ ]

List<Instant>

List of time values.

Location

Double[ ]

Coordinate value consisting of a latitude and a longitude.

Map

Map<String, String>

Dictionary of key/value pairs.

File

String

File content, generally referred to as static data in the context of ApiOmat. Generated POJOs hold the URL to this content. How to access static data content from within your service logic is described in the section below.

Image

String

Image-type file content, generally referred as static data in the context of ApiOmat. Generated POJOs hold the URL to this content.

Reference

DataModel

Reference to another ApiOmat data model object. DataModel corresponds to the referenced object type.

Reference[ ]

List<DataModel>

List of references to other ApiOmat data model objects. DataModel corresponds to the referenced object type.

Some of these data types will have specific content generated apart from the basic getters and setters.

Data type specific generated model content

Reference href

Every Reference attribute will also have a String attribute generated within the data model POJO corresponding to the URL from which the referenced object value can be retrieved, e.g. for a Reference attribute myRef:Java

@JsonProperty("myRefHref")
private String myRefHref = null;

Specific getter and setter

Apart from the general getters and setters generated for each of the data types, some have specific methods.

Every collection attribute has a method to add an item to it, e.g. for a data model MyClass with an attribute myStringList which is a String collection:Java

public MyClass addMyStringListItem(final String myStringListItem) 
{
if (this.myStringList == null) 
{
this. = new ArrayList<>();
}
 
this.myStringList.add(myStringListItem);
return this;
}


Every Map attribute has a method to add an item to it, e.g. for a data model MyClass with an attribute myMap:Java

public TestData putMyMapItem(final String key, final String myMapItem) 
{
if (this.myMap == null) 
{
this.myMap = new HashMap<>();
}
 
this.mapAttr.put(key, mapAttrItem);
return this;
}


Every Location attribute will have methods to get and set the latitude and longitude values individually, e.g. for a Location attribute myPos:Java

@JsonIgnore
public double getMyPosLatitude( )
{
...
}
 
@JsonIgnore
public double getMyPosLongitude( )
{
...
}
 
@JsonIgnore
public void setMyPosLatitude( double latitude )
{
...
}
 
@JsonIgnore
public void setMyPosLongitude( double longitude )
{
...
}

Static data and References

If a model has static data and/or reference attributes, enumeration classes are generated for each of those attributes. E.g. for a MyClass data model with both static data and reference attributes, MyClassRefAttributes.java and MyClassStaticDataAttributes.java will be generated within the model package of your microservice.

Class diagram

images/download/attachments/71325462/DataTypeClass.png

Why use these enumeration classes?

The goal of these enumeration classes is to ensure type safety when using the static data or reference related hooks of your service layer.
Let's make a concrete example for both static data and references:

Static data type example

Imagine that you created a Grocery model with an image attribute named groceryPicture; the following enumeration value will be generated:

GroceryStaticDataAttributes.java
/**
* Type and name definition of image attribute groceryPicture.
*/
GROCERYPICTURE( "groceryPicture", ApiomatTypes.IMAGE, Grocery.class )

The first argument corresponds to the name of your static data attribute, the second is the specific ApiOmat type of this attribute and the last argument is the class that holds it.

Now let's imagine that we want to retrieve the Resource stored in the YAMBAS database, for this we would use the service hook defined in the IBaseDataModelService (the exhaustive list of hook methods for services can be found in the Service classes documentation):

IBaseDataModelService
public StaticDataResource loadImage( String appName, String dataModelId, IStaticDataAttributeDefinition imageDefinition, String imageId, String token, String apiKey, String system, boolean show, TranscodingConfiguration conf );

Note the imageDefinition attribute. The fact that it is required to retrieve the resource ensures type safety - if your attribute has no IStaticDataAttributeDefinition representation, you will not be able to retrieve it.

Additional information

You may have already noticed that there are separate hooks for Image and File, but in both cases IStaticDataAttributeDefinition is used for type safety! The ApiomatTypes attribute of the definition is checked to make sure that the File hooks will not be used with an Image definition, or vice versa. This is done in the BaseDataModelServiceImpl class, which wraps each of your specific data model service implementation with before (where the check is done) and after logic. See the service architecture documentation for further info on the behavior of the BaseDataModelServiceImpl class.

Reference example

The principle of type safety, explained previously for static data, applies for references as well, with the addition that the specific DataModel type of the reference is checked.
Let's take the previous example of the Grocery model. We want a complex data type for the price, so we will create a Price data model. Our Grocery model will then hold a reference attribute "price" of type Price and the following enumeration value will be generated:

GroceryRefAttributes.java
/**
* Type and name definition of reference attribute price.
*/
PRICE( "price", Price.class, Grocery.class, false )

The first argument is the name of the attribute, the second is the type of the class referenced by this attribute (AKA the child class) the third is the class that holds the attribute (AKA the parent class) and the last argument is a boolean value that indicates whether the attribute is a collection.

As with static data, you can use the service hook defined in the IBaseDataModelService to load a referenced object:

IBaseDataModelService
public <Z extends AbstractDataModel> List<Z> loadReference( String appName, String dataModelId, IRefAttributeDefinition<Z> refDefinition, String q, boolean withReferencedHrefs );

The Reference attribute's type safety is ensured by the IRefAttributeDefinition. Additionally, the referenced object's type safety is ensured by using Java generics.

API data type oriented endpoints

The list of REST mapped methods generated within a data model controller depends on the data types of the model's attributes - so if e.g. your data model doesn't have any Reference attributes, there won't be any Reference oriented endpoints within that data model's controller. Here is the exhaustive list of all REST mapped method endpoints which are generated depending on attribute data types (replace <SERVICE_NAME> placeholder with your service name and <DATA_MODEL_NAME> with the data model name):

Note that all these endpoint paths should be prefixed with your service context path when queried. Also, in the following examples we deliberately avoided describing path parameters that are already shown in the endpoints path, such as appName or dataModelId.

Reference endpoints

Count

Returns the number of referenced class instances. Can be filtered with an ApiOmat query.

API path:

GET /apps/{appName}/models/<SERVICE_NAME>/<DATA_MODEL_NAME>/{dataModelId}/{refName}/count

Parameters:

Key

Type

Required?

Bound to

Description

q

String

False

Query

ApiOmat query to filter the database request

withReferencedHrefs

Boolean

False

Query

If true (default: false), the hrefs of referenced class instances will also be returned in the JSON representation.

Add

Add the given data model instance as a reference value.

API path:

POST /apps/{appName}/models/<SERVICE_NAME>/<DATA_MODEL_NAME>/{dataModelId}/{refName}

Parameters:

Key

Type

Required?

Bound to

Description

body

AbstractDataModel

True

Body

JSON representation of the referenced class instance to add

Get

Returns the referenced class instance(s) associated with the given reference attribute name. The return type is always a list of objects, which is composed of 0 to 1 elements if the reference attribute is for a single instance, and 0 to * elements if the reference attribute is a collection.

API path:

GET /apps/{appName}/models/<SERVICE_NAME>/<DATA_MODEL_NAME>/{dataModelId}/{refName}

Parameters:

Key

Type

Required?

Bound to

Description

q

String

False

Query

ApiOmat query to filter the database request

hrefs

Boolean

False

Query

If true (default: false), only the hrefs of the referenced class instances will be returned, otherwise their full JSON representations will be returned

withReferencedHrefs

Boolean

False

Query

If true (default: false), the hrefs of referenced class instances will also be returned in their JSON representations (if the hrefs parameter is set to true, there is no JSON representation, so this parameter can be skipped)

Delete

Remove a reference value (Does not affect the referenced instance).

API path:

DELETE /apps/{appName}/models/<SERVICE_NAME>/<DATA_MODEL_NAME>/{dataModelId}/{refName}/{refModelId}

Parameters: None

Image endpoints

Create key for restricted access

Create a transient key (AKA token) to access a restricted Image resource and return the key in the header. Only available if the attribute was configured to require a token to access it.

API path:

POST /apps/{appName}/data/images/<SERVICE_NAME>/<DATA_MODEL_NAME>/{dataModelId}/{refName}/{imageId}.key

Parameters:

Key

Type

Required?

Bound to

Description

validity

Long

True

Query

Validity time of the generated key in seconds

oneTime

Boolean

True

Query

If true (default), the key will only be usable once

apiKey

String

False

Query

The ApiOmat application API Key

system

String

False

Query

ApiOmat system (LIVE, STAGING, or TEST)

show

Boolean

False

Query

Set to true to view the image instead of downloading it. When set to false (default), the image will be sent as an attachment.

width

Integer

False

Query

For image transcoding; width in pixels

height

Integer

False

Query

For image transcoding; height in pixels

bgcolor

String

False

Query

For image transcoding; background color as hex value (FFCCBB)

alpha

Double

False

Query

For image transcoding; alpha value for the background

format

String

False

Query

For image transcoding; convert the image to a new format, you can use the following formats: png, jpg, gif or bmp

Create from Multipart

Create an Image from the given multipart content.

API path:

POST /apps/{appName}/data/images/<SERVICE_NAME>/<DATA_MODEL_NAME>/{dataModelId}/{refName}

Parameters:

Key

Type

Required?

Bound to

Description

file

MultipartFile

True

Body

File content as multipart resource

apiKey

String

False

Query

The ApiOmat application API Key

system

String

False

Query

ApiOmat system (LIVE, STAGING, or TEST)

format

String

False

Query

Image file extension without preceding dot (e.g. png, jpg...)

name

String

False

Query

Image file name

Create from binary

Create an Image from the given octet stream.

API path:

POST /apps/{appName}/data/images/<SERVICE_NAME>/<DATA_MODEL_NAME>/{dataModelId}/{refName}

Parameters:

Key

Type

Required?

Bound to

Description

file

Resource

True

Body

Image content as octet stream

format

String

False

Query

Image file extension without preceding dot (e.g. png, jpg...)

name

String

False

Query

Image file name

Get

Return a specific Image attribute resource.

API path:

GET /apps/{appName}/data/images/<SERVICE_NAME>/<DATA_MODEL_NAME>/{dataModelId}/{refName}/{imageId}.img

Parameters:

Key

Type

Required?

Bound to

Description

token

String

False

Query

One time access token

apiKey

String

False

Query

The ApiOmat application API Key

system

String

False

Query

ApiOmat system (LIVE, STAGING, or TEST)

show

Boolean

False

Query

Set to true to view the image instead of downloading it. When set to false (default), the resource will be sent as an attachment.

width

Integer

False

Query

For image transcoding; width in pixels

height

Integer

False

Query

For image transcoding; height in pixels

bgcolor

String

False

Query

For image transcoding; background color as hex value (FFCCBB)

alpha

Double

False

Query

For image transcoding; alpha value for the background

format

String

False

Query

For image transcoding; convert the image to a new format, you can use the following formats: png, jpg, gif or bmp

Delete

Delete a specific Image attribute.

API path:

DELETE /apps/{appName}/data/images/<SERVICE_NAME>/<DATA_MODEL_NAME>/{dataModelId}/{refName}/{imageId}

Parameters: None

Head

Return meta data about a specific Image attribute.

API path:

HEAD /apps/{appName}/data/images/<SERVICE_NAME>/<DATA_MODEL_NAME>/{dataModelId}/{refName}/{imageId}

Parameters:

Key

Type

Required?

Bound to

Description

apiKey

String

False

Query

The ApiOmat application API Key

system

String

False

Query

ApiOmat system (LIVE, STAGING, or TEST)

width

Integer

False

Query

For image transcoding; width in pixels

height

Integer

False

Query

For image transcoding; height in pixels

bgcolor

String

False

Query

For image transcoding; background color as hex value (FFCCBB)

alpha

Double

False

Query

For image transcoding; alpha value for the background

format

String

False

Query

For image transcoding; convert the image to a new format, you can use the following formats: png, jpg, gif or bmp

File endpoints

Create Key for restricted access

Create a transient key (AKA token) to access a restricted File resource and return the key in the header. Only available if the attribute was configured to require a token to access it.

API path:

POST /apps/{appName}/data/files/<SERVICE_NAME>/<DATA_MODEL_NAME>/{dataModelId}/{refName}/{fileId}.key

Parameters:

Key

Type

Required

Bound to

Description

validity

Long

True

Query

Validity time of the generated key in seconds

oneTime

Boolean

True

Query

If true (default), the key will only be usable once

apiKey

String

False

Query

The ApiOmat application API Key

system

String

False

Query

ApiOmat system (LIVE, STAGING, or TEST)

asstream

Boolean

False

Query

Set to true to view the file instead of downloading it. When set to false (default), the file will be sent as an attachment.

Create from Multipart

Create a File from the given multipart content.

API path:

POST /apps/{appName}/data/files/<SERVICE_NAME>/<DATA_MODEL_NAME>/{dataModelId}/{refName}

Parameters:

Key

Type

Required?

Bound to

Description

file

MultipartFile

True

Body

File content as multipart resource

apiKey

String

False

Query

The ApiOmat application API Key

system

String

False

Query

ApiOmat system (LIVE, STAGING, or TEST)

format

String

False

Query

File extension without preceding dot (e.g. txt, pdf...)

name

String

False

Query

File name

Create from binary

Create a File from the given octet stream.

API path:

POST /apps/{appName}/data/files/<SERVICE_NAME>/<DATA_MODEL_NAME>/{dataModelId}/{refName}

Parameters:

Key

Type

Required?

Bound to

Description

file

Resource

True

Body

File content as octet stream

format

String

False

Query

File extension without preceding dot (e.g. txt, pdf...)

name

String

False

Query

File name

Get

Return a specific File attribute resource.

API path:

GET /apps/{appName}/data/files/<SERVICE_NAME>/<DATA_MODEL_NAME>/{dataModelId}/{refName}/{fileId}.img

Parameters:

Key

Type

Required?

Bound to

Description

token

String

False

Query

One time access token

apiKey

String

False

Query

The ApiOmat application API Key

system

String

False

Query

ApiOmat system (LIVE, STAGING, or TEST)

asstream

Boolean

False

Query

Set to true to view the file instead of downloading it. When set to false (default), the file will be sent as an attachment.

Delete

Delete a specific File attribute.

API path:

DELETE /apps/{appName}/data/files/<SERVICE_NAME>/<DATA_MODEL_NAME>/{dataModelId}/{refName}/{fileId}

Parameters: None

Head

Return meta data about a specific File attribute.

API path:

HEAD /apps/{appName}/data/files/<SERVICE_NAME>/<DATA_MODEL_NAME>/{dataModelId}/{refName}/{fileId}

Parameters:

Key

Type

Required?

Bound to

Description

apiKey

String

False

Query

The ApiOmat application API Key

system

String

False

Query

ApiOmat system (LIVE, STAGING, or TEST)