Skip to content

Toro Cloud Dev Center


Quick start tutorial: Publishing a RESTful API

Estimated time to complete: 5-6 minutes

To help seamlessly integrate with external clients, you can also expose Martini services as RESTful web services. Fortunately, it's very easy to create a RESTful API using the Gloop REST API editor. Once published as a REST API, you can use any compatible client you like in order to invoke exposed services, such as Martini Desktop's HTTP Client, the API Explorer, or Postman.

This page will discuss some of these topics: how to create a RESTful API in Gloop, and how to invoke an API's endpoints using the HTTP Client.

Prerequisites to creating a RESTful API

This guide assumes you are already have the Martini package and service created in the previous pages of this tutorial. If you're unsure on how to prepare these items, read these other tutorial pages before delving into the instructions on this page:

Create a Gloop REST API

In order to publish a RESTful API, you need to create a Gloop REST API. This will contain path and service mappings, as well as other relevant information for building an API's Swagger, OpenAPI, and Postman schemas. To create a new Gloop REST API from scratch:

Creating a new Gloop REST API in Martini Desktop

Creating a new Gloop REST API in Martini Online

  1. Right click on the code directory of the hello package created on this page, then select New > Gloop API.
  2. Select Publish as the Type. Click Next.
  3. Specify Greet as the name of the API, and then select New REST API as the Type.
  4. Click Finish.

The Gloop REST API will appear in the Navigator with a .api file extension. Double click this item in order to open the file in the Gloop REST API editor if it's not already open.

Add a new path

A path is where a resource can be accessed by a client, which in this case is the service you would like to publish. To add a path to the Gloop REST API:

The Add Path button on the toolbar

  1. Click on the Operations tab.
  2. Click the Add Path button inside the Operations tab editor. This button appears when an API has no operations. If an API already has operations, paths can be added with the Add Path button on the toolbar.
  3. In the appearing dialog, provide the path you would like for the service. For this tutorial the path should be /hello/{name}. Path parameters are also supported, which is what's being used for mapping the name input property from the {name} part of the URL that will be used to invoke the service.
  4. Click Finish.

The Add Path button on the toolbar

  1. Click on the Operations tab.
  2. Click the Add Path button on the toolbar.
  3. In the appearing dialog, provide the path you would like for the service. For this tutorial the path should be /hello/{name}. Path parameters are also supported, which is what's being used for mapping the name input property from the {name} part of the URL that will be used to invoke the service.
  4. Click Finish.

Add an operation to the path

Gloop REST API operations are used to specify the type of actions (HTTP methods) supported by a path. A single path can have multiple operations. To add an operation to a path:

The Add Path button on the toolbar

The Add Path button on the toolbar

  1. Select the /hello/{name} path.
  2. Click the Add Operation button on the toolbar (highlighted on the screenshot above).
  3. From the appearing dialog, select GET in the available HTTP methods list.
  4. Click Finish.
The Gloop REST API editor is showing errors and warnings

While creating your API, you might notice gray, orange, and/or red warnings in the editor. These are meant to let you know of erroneous or incomplete parts of your configuration so that by the end, you'll be able to produce a standards-compliant API.

For this tutorial, you'll have to bind a service, parameter, and response to your operation to remove the warnings. Follow the instructions below to learn how.

Node Type Value
Service Greet.gloop
Parameter Path name
Response 200 OK greeting

Bind the operations to the service

With the operation present, you can now bind the Greet service. This service will be run when the matching URL and method is requested over HTTP.

Selecting a service for an operation

Selecting a service for an operation

  1. Double click the Value column of the Service node, and then click the button.
  2. Search and select the Greet.gloop service created here.
  3. Click OK.

Bind operation parameters

Because the Greet.gloop service is now bound to the operation, Martini can infer probable parameters. To add a parameter to the operation:

Selecting a service for an operation

Selecting a service for an operation

  1. Right click on any node under the hello/{name} GET operation node.
  2. Select New Parameter from the appearing context menu.
  3. Select PATH as the type of parameter to add, then click Next.
  4. On the Property drop-down, choose the name input property, then click Finish.

Bind operation responses

Because the service is now bound to an operation, Martini can also infer probable responses. To add a response to the operation:

Selecting a service for an operation

Selecting a service for an operation

  1. Right click on any node under the hello/{name} GET operation node.
  2. Select New Response from the appearing context menu.
  3. Select (200) OK as the status of the response, and enter a simple description. Click Next.
  4. Choose the greeting output property as the property which will be used as the response's content.
  5. Click Finish.

Add supported response formats

You can define supported response formats (content types) using the Produces node. These will be the acceptable values for received Accept request headers. If Martini receives a request with an Accept header that does not match any of the values defined under the Produces node, then Martini will reject the request and return a 406 (Not Acceptable) status code. To add a new Produces content type:

Adding `text/plain` response format support

Adding `text/plain` response format support

  1. Right click on the Produces node.
  2. Select New Produce from the appearing context menu.
  3. Specify the text/plain; charset=utf-8 as the type to add.
  4. Press .

Invoke the published endpoint using the HTTP Client

After saving via the shortcut (or by pressing the save button in the main toolbar), the API will be mapped and available in Martini, and will be available for clients to call after a couple of seconds.

To test if the API works, you can use Martini Desktop's HTTP Client. Because it's integrated in the IDE, it's very easy to generate a request for a Gloop REST API operation. To do this:

Invoking an operation over the HTTP Client

  1. Right-click on the operation.
  2. Select Invoke in HTTP Client from the appearing context menu.
  3. Configure the request to be sent via the HTTP Client view (which consists of setting the value of the name parameter).
  4. Click Send to finally send the request.