Skip to main content

Getting started

info

This page will explain how to get started through some short examples that generate a default REST interface for a DataElement.

What to expect​

The REST expanders can generate a full implementation for a REST API. These APIs will combine the REST protocol with several specifications and standard practices such as the HAL specification in JSON format. 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.

To ensure that we can provide a 100% generated API out of the box, we followed an approach similar to convention over configuration where we provide a solid default implementation for simple elements that will be sufficient in most cases. This is activated by using a uuid: String field as functional key, placing the resource identifiers in the includeJaxrsConnector option rather than in the options for the endpoints and by using the options exposeRestField, isUnique and isRequired for fields in a DataElement. This will couple the REST API to the data model, but this can be disabled on a per-field basis by not making use of those field options or for the entire DataElement by placing the resource identifiers in the options for the endpoints.

Setting up your project​

To get started, you have to add the REST expanders as an expansion resource to your application project. This can be done either in the µRadiant, or directly in the expansion settings file.

µRadiant​

  1. Open the model for your JEE application.
  2. Go the to settings tab.
  3. Add a new expansion resource with name net.democritus:rest-jaxrs-stack and version 5.2.1.

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="net.democritus:rest-jaxrs-stack" version="5.2.1"/>

Automatic API provisioning​

After adding rest-jaxrs-stack 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 fields 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 field with a specific name, it will use that field and key instead of adding the default externalId field.

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-expanders, the transmutation will not run! This includes using multiple fields or a non-string field as the functional key.

Manually modifying the model​

Your first connector​

  1. Create or choose a Component for the REST interface in your application.
  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 fields name and uuid with type String to the DataElement Example.
  7. Add the options generateUuid and isUnique to the uuid field, without any option values.
  8. Add the finder findByUuidEq to the DataElement Example.
  9. Add the option exposeRestField to the name and uuid fields 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 ValueFields 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 ValueFields 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 Field can be marked as unique, which will introduce additional uniqueness validations.

To mark the Example.name Field as unique:

  1. Add the option isUnique to the Field name in the DataElement Example.
  2. Add the finder findByNameEq and findByNameEq_UuidNe to the DataElement Example.
  3. Expand, build and deploy.