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:

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)

Data oriented content

ApiOmat data types conversion

Data type specific generated model content

Reference href

Specific getter and setter

Static data and References

Class diagram

Why use these enumeration classes?

Static data type example

Reference example

API data type oriented endpoints

Reference endpoints

Count

Add

Get

Delete

Image endpoints

Create key for restricted access

Create from Multipart

Create from binary

Get

Delete

Head

File endpoints

Create Key for restricted access

Create from Multipart

Create from binary

Get

Delete

Head

Search results