create restful services

Creating RESTful Services

Metl can be used to create and host RESTful services. Creating a RESTful service in Metl is as simple as creating a flow and deploying it to one of the configured agents. Metl comes with several sample flows that show the creation of RESTful services. The samples can be reviewed and run from the Samples project.

The core of Metl’s service capabilities come from the Http Request and Http Response components.

Following are instructions on how to create and host a REST service that lists all persons from a relational database. Metl REST services are created by configuring a Metl flow to accept the Http request, using other components to complete the logic of the flow, and then using the Http response component to return the results to the caller.

The first step in creating the sample REST service is to create the resource that will be used to gather the person data from the database. For this sample, an in memory H2 database will be used and is configured as follows:

Next, a model must be created to represent a person. In this example, the structure of the data of a person will be the same in the relational database source and the response of the REST service, so the same model will be used for both. Different models for each could be used and mapped within the flow, but for this sample, we’ll keep things simple. The person model looks as follows:

Now that our source resource and model are defined, the flow can be created that handles the serivce logic. The completed flow looks as follows.

First, let’s go through the non-service aspects of the flow. The SQL Executor labeled "Setup Person Database" is used in the sample flow to create the person table and populate it with data. The Gate component labeled "Ensure DB Setup Completes" is used to control the order of execution of the flow when an HTTP response triggers the flow to begin. It simply ensures SQL Executor "Setup Person Database" completes before reading the data from the database itself. In most scenarios, these two steps would not be necessary as the database where the data resides most likely already exists. These two steps are included in the sample simply to make it run stand-alone without the need for predefined database resources.

Next, let’s look at the Http Request component and its associated properties.

Each property above is described in the Http Request component definition. For this example, the "HTTP Method" of type "GET" and the "Path" of "/person/getAll" tells the flow to listen for HTTP GET requests to a URL of http://myserver:port/metl/api/ws/person/getAll, where "myserver" and "port" are the server and port on which Metl is running. If Metl is running locally on its standard port of 42000, HTTP GET requests to http://localhost:42000/metl/api/ws/person/getAll would be handled by the flow.

Once the request hits the flow, the "Setup Person" SQL Executor would run and setup the database. The "Ensure DB Setup Completes" Gate would ensure the SQL Executor is finished setting up the database before sending the HTTP request to the RDBMS Reader labeled "Read From Database". The RDBMS Reader component is set up as follows:

Note the output model of "Person" and the Sql of select * from person. The RDBMS Reader will simply read all rows from the person table and return the results based on the Person model. Once the data has been read from the database, it will be forwarded to the Serializer component configured as follows:

Now that the response has been formatted it send to the Http Response configured as follows:

Each property above is described in the Http Response component definition.

The following shows the results of a GET request to the service with an Accept header of application/xml.

<ArrayList>
	<item>
		<name>PERSON</name>
		<data>
			<GENDER>M</GENDER>
			<ID>1</ID>
			<LAST_NAME>Arbuckle</LAST_NAME>
			<FIRST_NAME>Garfield</FIRST_NAME>
		</data>
	</item>
	<item>
		<name>PERSON</name>
		<data>
			<GENDER>M</GENDER>
			<ID>2</ID>
			<LAST_NAME>Arbuckle</LAST_NAME>
			<FIRST_NAME>Odie</FIRST_NAME>
		</data>
	</item>
	<item>
	...
</ArrayList>

With an Accept header of application/json, the result would look as follows:

[
   {
      "name": "PERSON",
      "data":
      {
         "GENDER": "M",
         "ID": "1",
         "LAST_NAME": "Arbuckle",
         "FIRST_NAME": "Garfield"
      }
   },
   {
      "name": "PERSON",
      "data":
      {
         "GENDER": "M",
         "ID": "2",
         "LAST_NAME": "Arbuckle",
         "FIRST_NAME": "Odie"
      }
   }
   ...
]

If different XML or JSON formatting is desired, the flow can be configured to format entity based data into XML or JSON using the XML Formatter or custom scripts and the resulting text messages from the formatters can be passed to the HTTP Response component. The HTTP Response component will return the pre-formatted text (XML, JSON, or other) accordingly.

Tip	If the flow formats its own output, the HTTP Response component should be configured to communicate the content-type to the caller. This can be done by setting the HTTP Response "Content Type" accordingly (i.e. application/xml, etc.)

In order for a REST service flow to be used (run), it must be deployed to an existing Metl agent. See the Deploy section for details on creating agents and deploying flows.

To test the flow in the design mode, use the Run button and the flow will be auto-deployed to the design agent and a user interface will be presented for testing the web services.