Getting Started with Service API

info

This page will explain how to get started through some short examples that generate a default REST interface for a DataElement. More extensive documentation on API Integration can be found here.

The service API expandersExpanderA unit of generation that combines a data tree instance (functional M1 model) with a template to generate an artifact. can generate a full implementation for a REST API. While by default there is extensive code generation, the developer still has to write some custom code to provide the needed logic for the REST API. This is due to the absence of a meta-model to represent the REST API at this time.

Setting up your project

To get started, you have to add the service API expandersExpanderA unit of generation that combines a data tree instance (functional M1 model) with a template to generate an artifact. as an expansion resourceExpansion Resource (ExpansionResource). A reusable resource bundle containing expanders and features that provide specific application capabilities, defined in the expansion settings and added to the classpath during expansion. to your applicationApplicationThe overarching model container grouping all components, domain logic, and configurations for an enterprise solution. project. This can be done either in the µRadiant, or directly in the expansion settingsExpansion Settings (ExpansionSettings). The core XML configuration file specifying model locations, target expansion output directories, and expansion resources. file.

µRadiant

1. Open the model for your JEE application.
2. Go the to settings tab.
3. Add a new expansion resource with name org.normalizedsystems.beam:service-api-beam and version 2.0.2.

Project files

1. Open the expansion settings file for your application, which is often found in the conf folder in the root of your project's workspace with the name expansionSettings.xml.
2. Add a child element to expansionResources as follows:

   <expansionResource name="org.normalizedsystems.beam:service-api-beam" version="2.0.2"/>

Automatic API provisioning

After adding service-api-beam to a project, new transmutations will become available to automatically provision default API implementations for an existing model. These can be executed through right-clicking the element model element in the µRadiant, where the transmutation will be listed in the menu, or through command-line using Maven.

Transmutation

CreateDefaultRestApiComponent

This transmutation will add a default REST API to an entire component. That means that it will add the default Component options such as enableJaxrs and then run the AddDefaultRestApi transmutation on every DataElement in that Component.

Transmutation

AddDefaultRestApiDataElement

This transmutation will enrich the model for a single DataElement will all of the model elements needed to fully expose the element through a default connector implementation with all fieldsFieldA property of a DataElement expanded to a database column and user interface input element. in the element being exposed one-to-one through the API.

Where possible, the transmutation takes into account the current state of the model for the DataElement and provisions it accordingly. For example, if you already set a functional key to a fieldFieldA property of a DataElement expanded to a database column and user interface input element. with a specific name, it will use that fieldFieldA property of a DataElement expanded to a database column and user interface input element. and key instead of adding the default externalId fieldFieldA property of a DataElement expanded to a database column and user interface input element..

note

The transmutation only applies changes if the option enableJaxrs is present on the Component of which the DataElement is part.

caution

If your model violates some of the base requirements of the rest-expandersExpanderA unit of generation that combines a data tree instance (functional M1 model) with a template to generate an artifact., the transmutation will not run! This includes using multiple fieldsFieldA property of a DataElement expanded to a database column and user interface input element. or a non-string fieldFieldA property of a DataElement expanded to a database column and user interface input element. as the functional key.

Manually modifying the model

Your first connector

1. Create or choose a Component for the REST interface in your applicationApplicationThe overarching model container grouping all components, domain logic, and configurations for an enterprise solution..
2. Add the option enableJaxrs, enableSwagger and enableValidation to the Component.
3. Add a DataElement to the Component which you wish to expose through the API. Give it a name like Example.
4. Add the option includeJaxrsConnector to the DataElement Example, with the option value /examples/{exampleId}.
5. Add the options exposeGetEndpoint and exposeGetListEndpoint to the DataElement Example.
6. Add the fieldsFieldA property of a DataElement expanded to a database column and user interface input element. name and uuid with type String to the DataElement Example.
7. Add the options generateUuid and isUnique to the uuid fieldFieldA property of a DataElement expanded to a database column and user interface input element., without any option values.
8. Add the finderFinderA search specification combining field-operator pairs to execute standard data queries on a DataElement. findByUuidEq to the DataElement Example.
9. Add the option exposeRestField to the name and uuid fieldsFieldA property of a DataElement expanded to a database column and user interface input element. of the DataElement Example.
10. Add the option functionalKey with value uuid to the DataElement Example.
11. Expand, build and deploy.

Your API for the Example DataElement is now available at path /applicationName/v1/examples. You can view the API documentation for the API at /applicationName/swagger/componentName.

Adding input endpoints

Every input endpoint (POST, PUT, PATCH, DELETE) can be defined as a combination of an option and a DataCommand with a specific name. The implementation of the logic for these endpoints must be done in custom code in their respective CommandExtension classes, except when generating default implementations.

POST endpoint

To add a POST endpoint to the DataElement Example:

1. Add the option exposePostEndpoint to the DataElement Example.
2. Add the DataCommand createExample to the DataElement Example.
3. Add the option jaxrs.command.create to the DataCommand.
4. In the DataCommand, add ValueField name, with the type String.
5. Expand, build and deploy.

PUT endpoint

To add a PUT endpoint to the DataElement Example:

1. Add the option exposePutEndpoint to the DataElement Example.
2. Add the DataCommand modifyExample to the DataElement Example.
3. Add the option jaxrs.command.modify to the DataCommand.
4. In the DataCommand, add ValueFieldsFieldA property of a DataElement expanded to a database column and user interface input element. exampleId and name, both with the type String.
5. Expand, build and deploy.

PATCH endpoint

To add a PATCH endpoint to the DataElement Example:

1. Add the option exposePatchEndpoint to the DataElement Example.
2. Add the DataCommand updateExample to the DataElement Example.
3. Add the option jaxrs.command.update to the DataCommand.
4. In the DataCommand, add ValueFieldsFieldA property of a DataElement expanded to a database column and user interface input element. exampleId and name, both with the type String.
5. Expand, build and deploy.

DELETE endpoint

To add a DELETE endpoint to the DataElement Example:

1. Add the option exposeDeleteEndpoint to the DataElement Example.
2. Add the DataCommand removeExample to the DataElement Example.
3. Add the option jaxrs.command.remove to the DataCommand.
4. In the DataCommand, add the ValueField exampleId with the type String.
5. Expand, build and deploy.

Marking a field as unique

A FieldFieldA property of a DataElement expanded to a database column and user interface input element. can be marked as unique, which will introduce additional uniqueness validations.

To mark the Example.name FieldFieldA property of a DataElement expanded to a database column and user interface input element. as unique:

1. Add the option isUnique to the FieldFieldA property of a DataElement expanded to a database column and user interface input element. name in the DataElement Example.
2. Add the finderFinderA search specification combining field-operator pairs to execute standard data queries on a DataElement. findByNameEq and findByNameEq_UuidNe to the DataElement Example.
3. Expand, build and deploy.