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 services. In Swagger and OpenAPI, these mappings are referred to as operations. This tab is similar to the 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.

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:

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 is for assigning HTTP request methods, parameters, and responses to a 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.

Adding a new operation

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 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.

  

  

• 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.

TRACE support

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.

Operation fields

After adding an operation to the API, more fields appear.

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 service to be executed for the operation.
Parameters	A collection of parameters to be provided to the service.
Responses	A collection of possible responses the operation will return in response to a request.
Response Code Field	Used to determine the which response to return.
Tags	A collection of tags for API documentation control. Tags can be used for logical grouping of operations by resources or any other qualifier.
Documentation	Resources that document the operation.
Consumes	A collection of MIME types that the operation can consume.
Produces	A collection of MIME types that the operation can produce.
Mock	A flag for enabling response mocking.
Deprecated	A flag for marking the operation as deprecated.
Enabled	A flag for enabling or disabling the operation.

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.

Service

The Service node defines the service to be executed for a given operation. You can change an operation's service through the service picker. In the editor, you can open this dialog by double clicking the Service node, and then clicking on the appearing button.

Drag and drop service files to operation nodes

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

Comments as documentation

When a 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 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.

Creating a new service

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

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, you can open it from the Navigator view.

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 service editor will appear. Doing this on certain types of nodes will open up the editor with focus on a service property.

Parameters

Parameters in a Gloop REST API are used to map HTTP request data to the input properties of a service. Thankfully since 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 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 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.

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:

• 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.

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.

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:

Your mock response payload can be set via the Body Mock Data field. Currently, the only supported payload formats are text, JSON, XML and YAML. 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.

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 and categorize operations.

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

The API Explorer uses tags to determine which operations are related to each other, and then display them together like so:

If an operation doesn't have a tag, it will be displayed under 'default'.

Global tags

You can manage API-wide tags through the Tags tab.

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.

{
  "result" : "ERROR",
  "apiErrorCode" : -1,
  "message" : "Not found"
}

Deprecating an operation

You can flag an operation as 'deprecated' to discourage clients from using it. Although usage is discouraged, deprecated operations are still functional endpoints. You can toggle the Deprecated property value between true or false by pressing . When set to true, the operation node's label will be suffixed with '(Deprecated)', and a warning indicating the operation is deprecated will be shown on hover, like so:

Disabling an operation

You can disable all operations defined in a Gloop REST API by un-checking the Enabled checkbox at the top right-hand side of the editor. However, in some cases, you may only need to disable some, but not all operations.

To individually enable or disable an operation, you can toggle the operation's Enabled property. When set to false, the operation node's label will be suffixed with '(Disabled)'. Upon hovering over the disabled operation, a warning will also be displayed, indicating that it is disabled.

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.

Link to API Explorer

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

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.

Using the Clipboard

The Operations tree allows you to cut, copy, and paste nodes in order to move or duplicate nodes as required. For example, you can copy an operation from one path and paste it under another path, as shown below:

You can copy and paste operation properties, and even paths. Plain text editor can also be copied to the clipboard and pasted anywhere in the tree.