Skip to main content

Create and Consume Services

Create a Service​

Build services on top of data queries to consume modeled data systematically. To create a service select New Service from the drop down menu to launch the Service Editor

General Tab​

In the General tab of the Service Editor, users can specify metadata of their service including the service URL, documentation and owners. URL parameters can be directly defined within the {} sytnax.

Service Editor - General

Execution Tab​

In the execution tab, users can create and edit their service query. By hitting the pencil icon button, users can edit the query using the Query Builder. Users can make changes to the query either in the user-friendly form mode or in text mode.

Additonally the bottom panel lets you define your execution context which represents the mapping and runtime used when executing your query.

Multi Executions lets you use a service parameter to decide what execution context (mapping, runtime) to use. You can switch between multi and single using the top right icon on the context panel.

Service Editor - Execution

Tests Tab​

This panel lets you define tests for the services you write by specifying test data, serialization format of your test and the assertions.

See features in action​

Create a Service​

Create a Service

Create a multi execution service​

Create a multi execution service

Create a Service Test​

After setting up general information about your service as well as execution details, you can generate test data with a click of a button (or use test data you created). We highly encourage setting up tests for all services running in production. More details and video walkthrough here.

Create connection test data​

Click the generate button to automatically generate test data if possible. Otherwise, manually create test data.

Create re-usable test data.​

You can create test data in the Data element that can be easily re-used across all your service tests in your Studio project. This includes test data for external formats, relational stores and service stores. We are working on making the same functionality available in mapping tests as well - stay tuned! More details and video walkthrough here.

Relational​

Add relational data tables based on databases to which the service's mapping connects.

It is unnecessary to provide all columns with test data. The columns used in the service, however, require test data. Besides, the primary keys have to be distinct. Create connections test data - Relational

External Format (M2M)​

Click the generate button to automatically generate test data if possible. Otherwise, manually provide test data for the source class' properties that serve as the foundation for the properties used in the service. e.g. As shown in the video, _Firm's name is used in the service, which comes from Firm's legalName. Therefore, manually providing test data for legalName will be sufficient if the generate button is not working. Create connections test data - Relational

Data element​

More examples of different types of Data element creation could be found here. Create connections test data - Data Element

Service Store​

Create connections test data - Data Element

Relational​

Create a service test - Relational

Model to Model​

Create a service test - M2M

Service Store​

Create a service test - ServiceStore

With Data Element​

Create a service test - DataElement

With Parameters​

Create a service test - Parameters

Promote a model-to-model mapping query to a service​

  1. Create a model-to-model mapping (find instructions here) and select the Promote to Service icon.

  2. Add a name for the service and hit create to launch the Service Editor.

Promote a relational-to-model query to a service​

This feature is not yet supported.

Consume a Service​

Consume data services via executable service JAR files. As part of the project build, an executable JAR file is generated for each service defined in the project. The executable service JAR file will be published in the Gitlab project that stores the data model code. The JAR file can be consumed by any Java application.

Creating and Consuming a Service Execution JAR file​

Introduction​

Prerequisites​

  • A Legend Studio project with a Service model
  • Familiarity with the following Legend concepts :
    • Data modeling with classes, associations
    • Data modeling with stores, mappings, connections and runtimes
    • Data modeling with Legend services

Showcase project​

1. Service Execution Primer​

A "service execution" jar is a Java library generated from a Legend model.

Consider the service model below. It is a grouping of a data access query, a mapping to a physical (relational) store and a specific database connection.

Service service::persons
{
  pattern: '/api/persons';
  documentation: '';
  autoActivateUpdates: true;
  execution: Single
  {
    query: |domain::Person.all()->project([x|$x.name, x|$x.firmId], ['Name', 'FirmId']);
    mapping: mapping::firmperson;
    runtime: runtime::firmperson;
  }
}

2. Service Execution Class​

Once modeled in Legend, the Legend project's SDLC infrastucture consumes this model and generates a Java class.

personsService service = new personsService();

When executed, this class connects to the database specified in the model, queries and returns the data.

3. Building a Service Execution Jar​

In the simplest case, a service execution jar is autogenerated by the Legend project's SDLC.

To generate a service execution jar using Legend SDLC:

  • Create a Legend Studio project
  • Use Legend Studio to create a Legend model. This model should include a service definition as shown above
  • Use Legend Studio SDLC controls or native Gitlab controls to merge your model to the master branch
  • Once merged, the Gitlab pipeline configured by Legend SDLC runs a code generation plugin which generate a service execution jar
  • The Gitlab pipeline also publishes the generated jar to a Gitlab Maven registry.

As a concrete example:

4. Using a Service Execution Jar​

Just as with other stores in Legend, the logical model is mapped to the logical definition of the store.

Once a jar has been created it can be consumed like any other jar in a Java application. See:

Retrieve Services Metadata via API Endpoints​

Coming soon.

See features in action​

consume a service

More​