Skip to content

Home

Development

IDEs

API Explorer

Releases

Release notes

Martini Runtime

Martini Desktop

Martini Online

Feature requests

Bug reports

Gloop REST API editor, Operations tab

The Operations tab is perhaps most important tab in the Gloop REST API editor. This is where all of the paths are mapped to their respective Gloop services. In Swagger and OpenAPI, these mappings are referred to as operations. This tab is similar to the Gloop service editor and the Gloop model editor in that they have a toolbar at the top, and support a wide range of content-assist proposals to make editing faster and easier.

The Operations editor is packed with many features; so to make navigation easier, it's been divided into multiple sections. On this page, we will describe in detail how the Operations editor works, and how changes made in the editor affect the resulting Swagger, OpenAPI, and Postman definitions.

OpenAPI and Swagger specification resources

This page mainly links to the OpenAPI specification, since both the Swagger and OpenAPI specifications are similar. If there are differences in how Gloop builds the resulting Swagger and OpenAPI definitions, then this page will link to both sources and describe the differences.

Toolbar

Below is a screenshot of the Operations editor's toolbar, and a table listing what each button in the toolbar is used for.

Gloop REST API editor, Operations toolbar

Gloop REST API editor, Operations toolbar

Button Description
New Path Adds a new path to the REST API. This maps to the Swagger or OpenAPI Path Item Object.
New Operation (Wizard) Opens a wizard prompting you to choose a service and request method to add to a selected path in the Operations editor, which then results in a new operation being added to the API. This maps to the Swagger or OpenAPI Operation Object.
New Body Parameter Adds a parameter to an operation. This maps to the Swagger Parameter Object, whose in value is body, and the OpenAPI Request Body Object.
New Parameter Adds a parameter to an operation. This maps to the Swagger or OpenAPI Parameter Object.
New Response Adds a response to an operation. This maps to the Swagger or OpenAPI Response Object.
New Tag Adds a string to the list of tags for the operation.
New Consume Adds a new consume entry to the operation.
New Produce Adds a new produces entry to the operation.
Edit Response Header Edits the model used to represent response headers of the operation.
Edit Edits the value of the selected row in the Operations tree.
Delete Deletes the current entry from the Operations editor.
Collapse All Collapses all nodes in the Operations editor.
Expand All Expands all nodes in the Operations editor.
Link to API Explorer Opens and links the selected operation to the corresponding operation in API Explorer.
Enabled Enables and disables the API. If the API is disabled, it's still editable but no operations will be exposed.

Base path

All operations in the API will have their URLs prefixed with the configured base path. If you have a base path value of /myApi, and an operation mapped to /myOperation, then Martini will expose the operation at http://<host>:<port>/api/myApi/myOperation.

The base path isn't supported by the OpenAPI specification, so Gloop treats the base path a little differently. When generating Swagger definitions, it's added to the basePath field. However, since OpenAPI doesn't have a basePath field, it instead gets added to the generated url field in the Server Object.

API versioning

The base path is a great place to include a version number to the URL of your API. This way, as your API changes over time, you can create a new REST API with a different version number in its base path allowing multiple versions of your API to run concurrently.

Paths

Now it's time to delve into the main part of the editor - the Operations editor tree. The editor tree is split into two columns: Path and Value. The Path column shows the REST API in a tree-like structure, whereas the Value column is used for populating the various fields. For populating or maintaining a field, you can either press on the highlighted row or double click on the value itself. Some fields, when they're editable, display a button on the right-hand side. Clicking on this button will open a dedicated editor for the field.

The first thing that needs to be added to the tree when creating an API is a Path Item Object. The editor has four ways in which you can add a path:

  • The add-path button in the toolbar.
  • Using the context menu in the editor.
  • Pressing in the editor.
  • Using content assist by pressing in the editor, and then choosing Path.

The images below shows all four methods, in order:

Adding a new path via toolbar

Adding a new path via context menu

Adding a new path via hotkey

Adding a new path via content-assist

Adding a new path via toolbar

Adding a new path via context menu

Adding a new path via hotkey

Adding a new path via content-assist

To edit the value of a path, press while it is selected. Don't forget that Swagger, OpenAPI, and Postman all support path templating in the path; Gloop is also no different.

Operations

An Operations node can be found under every path. This part of the editor for assigning HTTP request methods, parameters, and responses to a Gloop service.

Get help at any moment

You can hover over items under the Operations node to trigger tooltips which display information about the hovered field.

Tooltips appearing in the Operations node

Tooltips appearing in the Operations node

Similar to adding a path, there are four ways to add an operation to a path:

  • Using the New Operation button in the toolbar, which is enabled when a path is currently selected. When this is used, a small wizard will appear asking for which request method and Gloop service to map.
  • Using the context menu in the editor, which you can trigger by right clicking an Operations node. When this option is used, the Service node will have focus after the HTTP method is added. Pressing or clicking the button allows you to choose a service.

    Adding an operation via the context menu

    Adding an operation via the context menu

  • Pressing a hotkey in the editor while the focus is on or under the Operations node. The hotkeys are as follows:

    Hotkey Request Method
    GET
    POST
    PUT
    PATCH
    DELETE
    HEAD
    OPTIONS
    TRACE
  • Using content-assist, which is triggered by pressing in the editor while the focus is on or under a a node, and choosing an HTTP request method. The content assist will then prompt for a service to be chosen.

The Swagger specification does not support the TRACE method. Any operation that uses TRACE will not be added to the generated Swagger definition. Also, Tomcat doesn't allow TRACE requests by default; it needs to be enabled.

When an operation is added to the API, more fields appear such as:

Field Name Description
Description A verbose explanation of the operation behavior. CommonMark syntax may be used for rich text representation.
Summary A short summary of what the operation does.
Service Required. The Gloop service to be executed for this operation.
Tags A list of tags for API documentation control. Tags can be used for logical grouping of operations by resources or any other qualifier.

Comments as documentation

When a Gloop service is mapped to an operation in the editor, its comments are automatically added to the Description field in gray text. This is to tell you that the API itself has no documentation, but the comments from the Gloop service will be used. Also, the comments that are in your input and output properties are included in your parameters and responses. You can overwrite them by pressing enter on any of these fields.

Opening a service from the Gloop REST API editor

You can open the service used by a Gloop REST API by clicking any node under the operation node, and then selecting Open Declaration. You can also press on the selected node to do the same. Soon, a new tab for the service in the Gloop service editor will appear. Doing this on certain types of nodes will open up the editor with focus on a Gloop service property.

Opening the declaration of a service property set as the body parameter

Opening the declaration of a service property set as the body parameter

Converting operation method

An operation's HTTP method type can be modified while persisting configuration set with the previously specified HTTP method. To convert an operation's method, right click anywhere in the operation node to show the context menu, choose Convert To, then select any HTTP method you want.

Converting an operation's method

Converting an operation's method

Creating a new Gloop service

If you're not satisfied with the current roster of services, you can create a new Gloop service for your API operation instead while in the REST API editor. To do this:

Creating a new gloop service in the Gloop REST API editor

Creating a new gloop service in the Gloop REST API editor

  1. Select the Service node.
  2. Press to activate content assist and choose New Service from the list of proposals. A wizard will appear.
  3. Specify the name of your service.
  4. Click the Finish button.

Afterwards, the value of the Service field would change; it will now point to the newly created service. The service will be created under the same directory as the Gloop API by default, but this can be changed while in the wizard.

The service will only be created; it is still empty. To edit, open it from the Navigator view.

Drag and drop Gloop service files to operation nodes

Martini allows you to drag and drop a Gloop service from the Navigator view to (anywhere in an) operation node to set the Service field.

Dragging and dropping a service to a Service node

Dragging and dropping a service to a Service node

Parameters

Parameters in a Gloop REST API are used to map HTTP request data to the input properties of a Gloop service. Thankfully since Gloop services clearly define their inputs, the editor makes it easy to map them to the REST API. Like operations and paths, there are four ways to add a parameter to an operation:

  • Using the New Parameter button in the toolbar, which is enabled when an operation is selected. When you use this method, a new parameter will appear under the Parameters node. You can change the parameter using the drop-down in focus. The choices on the dropdown are based on the selected Gloop service's input properties.
  • Using the context menu in the editor, which you can view by right clicking on a Parameters node.
  • Pressing in the editor while an operation node is selected. The selected service must have input parameters; else, using the hotkey will do nothing.
  • Using content assist; which is triggered by pressing while in the editor, and choosing Parameter. Martini will then prompt for an input property, and location to be chosen. If you are already on or underneath the Parameter node in the editor, the content assist will also list the input properties for you. Valid choices for the parameter location are:

    Location Description
    Path Used together with path templating, where the parameter value is actually part of the operation's URL. This does not include the host or base path of the API. For example, in /items/{itemId}, the path parameter is itemId.
    Parameter Parameters that are appended to the URL. For example, in /items?id=###, the query parameter is id.
    Header Custom headers that are expected as part of the request. Note that RFC7230 states header names are case insensitive.
    Cookie Used to pass a specific cookie value to the API. Swagger doesn't support cookie parameters so every time you ask Martini to generate a Swagger definition with a cookie parameter, it will log a warning message.
    Form Form style parameters defined by RFC6570.

    Aside from selecting already existing input properties of the service, you can also create a new input property straight from content-assist.

Sync your REST API configuration and service

When a Gloop service's inputs or outputs have updated but is used in an opened Gloop REST API file, you can either press or click on the Refresh context menu to sync it in the Gloop REST API editor.

Adding a new parameter via the toolbar

Adding a new parameter via the context menu

Adding a new parameter via hotkey

Adding a new parameter via content assist

Adding a new parameter via the toolbar

Adding a new parameter via the context menu

Adding a new parameter via hotkey

Adding a new parameter via content assist

Parameters also have a Description field, which is for supplying a brief description of the parameter. This could contain examples of use. CommonMark syntax may be used for rich text representation.

Request bodies

When an HTTP request method supports the inclusion of a request body, a Body Parameter node will appear under the corresponding operation node. To set the body parameter of an operation, you can either:

  • Select the Body Parameter node then press to edit. Use your and arrow keys or click on the dropdown box to select which service input property should be mapped as the request body.
  • Use content assist, which is triggered by pressing in the editor. Before you trigger the content assist feature, ensure the operation node you want to edit is in focus. In the list of proposals, you will be able to select existing input properties as the body parameter. If you wish, you can create a new property for the Body Parameter field by selecting Add property.

Responses

Gloop REST APIs use response configurations to determine which properties to write to the HTTP response, and which HTTP response code to send with it. As with parameters, since Gloop lists all output properties, mapping responses is easy. And like parameters, there are four ways to add a response to an operation:

Adding a new response via the toolbar

Adding a new response via the context menu

Adding a new response via hotkey

Adding a new response via content assist

Adding a new response via the toolbar

Adding a new response via the context menu

Adding a new response via hotkey

Adding a new response via content assist

  • The New Response button in the toolbar, which is enabled only when an operation node is selected. Once you click on this button, a dialog will appear, asking for the details of your response. Using the dialog, you'll be able to set the response's status, description, body, and headers. When choosing a body or header, you can select from existing properties from the service, or create new ones.
  • Using the context menu in the editor, which you can view by right clicking on an operation node.
  • Pressing in the editor while an operation node is selected.
  • Using content assist, which is triggered by pressing in the editor, and choosing Response from the list of proposals. With this option, the content assist will immediately prompt for response code. After providing a response code, it will let you choose the response body either by selecting an existing property or adding a new code, it will let you choose the response body either by selecting an existing property or adding a new output property.

Response headers

Many REST APIs send response headers to provide consumers with extra information without cluttering the response body itself. Gloop also supports this and it's easy to add them to your API.

In your service, add an output model with any name, and add properties whose names match the header names, and populate them. Here is a screenshot of a model that will return a Content-Type and X-API-Limit header.

Sample output model for services with response headers

Sample output model for services with response headers

Object aliases

If an invalid Java or Groovy name is used for a Gloop property, like in the case of headers, Gloop automatically assigns an alias for the property.

To map a REST API operation to a model for use with response headers, simply highlight the Headers node underneath a response in the editor tree, then either press or double-click on it to choose an output model.

Setting the headers of a REST operation response

Setting the headers of a REST operation response

Mocking responses

An API-first approach means for every given developmental project, defining the specifications of the API comes first; especially before coding business requirements. The API is used as a contract; firmly establishing what the product can and can't do. By creating the contract first, developers can avoid the nightmare of integrating multiple applications with no firmly established rules and boundaries.

Martini further supports the API-first approach by allowing data mocking. Through data mocking, you can create artificial API responses without having to write code; thus allowing you to focus on what matters – API design.

For Gloop REST APIs, data mocking can be enabled per operation by setting the Mock property to true. When this property is set to true, the operation node's label will be suffixed with (Mock), like so:

Operation with data mocking enabled

Operation with data mocking enabled

Your mock response payload can be set via the Body Mock Data field. Currently, the only supported payload formats are text, JSON, and XML. The format selected must be specified in the Produces node as well. Your payload can be anything, as long as it is written in the format selected. For randomized payloads, random values will be generated.

If your response node's Body or Headers node is configured, Martini will try to populate its respective Body Mock Data payload based on the data types configured in the Body or Headers node. Providing the Body or Headers node is optional.

Setting response mock data

Setting response mock data

Response Code Field

Below the Responses node is another node called Response Code Field. This is what Gloop uses at runtime to determine which response to use. Services used in Gloop REST APIs must only return the status code in this property. If the value of the Response Code Field is null, or not numeric, then a warning message will be logged and a response code of 200 will be assumed.

Tags

The Tags node allows you to configure the associated tags for an operation. Tags are used to group or categorize operations. You can manage your tags through the Tags tab.

To add a new tag, press , or use content assist by pressing . To edit all tags in one simple dialog, double-click the Tags node or press while it's in focus.

Editing operation tags

Editing operation tags

Documentation

The Documentation node of an operation maps to the OpenAPI External Documentation Object. The descriptions for documentation-related fields are as follows:

Field Name Description
Documentation URL Required. The URL for the target documentation. Value must be in the format of a URL.
Description A short description of the target documentation. CommonMark syntax may be used for rich text representation.

Consumes

The Consumes node in the Gloop REST API editor contains a list of strings, which should contain MIME-types. For Swagger, this maps directly to the consumes field in the Swagger Operation Object. For OpenAPI, it will create a new entry in the content field of the operation's Request Body Object.

Produces

The Produces node in the Gloop REST API editor contains a list of strings, which should contain MIME-types. For Swagger, this maps directly to the produces field in the Swagger Operation Object. For OpenAPI, it will create a new entry in the content field of the Response Object.

Use any value declared under the Produces node for request Accept headers

When sending a request to your Gloop REST API, ensure your request has an Accept header whose value is any of the values declared under the Produces node. Not doing so will return a "Not found" message.

1
2
3
4
5
{
  "result" : "ERROR",
  "apiErrorCode" : -1,
  "message" : "Not found"
}

Outline view

Martini has an Outline view that can be used to filter and help you find what you're looking for in the Operations tab. In Martini Online, this is shown by default. To open this view in Martini Desktop, go to the Quick Access bar, type outline, and then select Outline (General) from the list of results.

The Outline view in the Operations tab

The Outline view in the Operations tab

You can preview Gloop REST API operations in API Explorer using the Link to API Explorer button from the toolbar, highlighted below:

Link the active REST API Editor to API Explorer toolbar

Link the active REST API Editor to API Explorer toolbar

When navigating from operation to operation in the REST API editor, you will notice that the API Explorer also jumps from page to page. It displays the currently selected operation from the editor. Through this feature, you can work alongside API Explorer, so you can easily try your operations, and see the operation's documentation.

Link active REST API Editor with API Explorer

Link active REST API Editor with API Explorer