Skip to content

Overview

Development

Overview

IDEs

API Explorer

Gloop REST API Operations Editor

The Operations editor is packed with many features; so to make navigating this page easier, it's been divided into multiple sections or tabs. Here, we will describe in more 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.

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 TORO Integrate 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 both 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, simply press while it is selected. Don't forget that Swagger, OpenAPI, and Postman all support path templating in the path, and Gloop is no different.

Operations

This part of the editor is about assigning HTTP request methods, parameters and responses to a Gloop service.

Get help at any moment

You can hover over nodes in the Operations tree to show tooltips which display information about the field.

Tooltips appearing in the Operations tree

Tooltips appearing in the Operations tree

Adding an Operation

Similar to adding a path, there are four ways of adding an operation to the editor:

  • 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 the request method and Gloop service to map it to.
  • Using the context menu in the editor, which you can trigger by right clicking on the Operations node. When this option is used, the operation is added, and the button beside the Gloop service has focus. Pressing or clicking on 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 current selection 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 current selection 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, which you can read more about here.

When an operation is added to the API, more fields appear, and some of these fields are described below:

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

Converting an Operation's Method

An operation's HTTP method type can be modified while persisting configuration set with the previously specified HTTP method. To convert an operation, right click anywhere in the operation node to show the context menu, choose Convert To, then click on 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 (Create button, if you're using Coder Cloud).

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 Coder Navigator view.

Drag and drop Gloop service files to Operation nodes

Coder allows you to drag and drop a Gloop service from the Coder 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 in the editor as a drop-down selection. Use the cursor keys or highlight the drop-down to choose the input property of the Gloop service to map to the parameter.
  • 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. The content-assist 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 TORO Integrate 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/parameter straight from content-assist.

Sync your REST API configuration and service

When a Gloop service's inputs or outputs have updated and is open in the REST API editor, you can either press or click on the Refresh context menu item to sync it with the editor.

Adding a new parameter via the toolbar

Adding a new parameter via the context menu

Adding a new parameter via the context menu

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 the context menu

Adding a new parameter via content assist

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

Request Bodies

When the HTTP request method supports the inclusion of a request body, the Body Parameter node will appear under the 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 selected. 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 the response configuration to determine which output property 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. Both the Status and Description fields are required by the Swagger and OpenAPI specifications.
  • 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 ask you to choose specify the response body either by selecting an existing property or adding a new output property.

Below the Responses node is another node called Response Code Field. This is the field that 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.

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, simply 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, we can avoid the nightmare of integrating multiple applications with no firmly established rules and boundaries.

Coder Studio further supports the API-first approach by allowing data mocks. 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

Setting Response Mock Data

Your mock response payload can be set via the Body Mock Data field. Currently, the only supported payload formats are text, JSON, and XML. Your payload can be anything, as long as it is written with the format selected.

If your Response node's Body or Header field is configured, Coder will try to populate its respective Body Mock Data payload based on the data type configured in the Body or Header field. Providing the Body or Header field is optional.

Setting response mock data

Setting response mock data

Documentation

The Documentation node of an operation maps to the OpenAPI External Documentation Object. As such, 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.

The Outline View

Both Coder Cloud and Coder Studio have an Outline view that can be used to filter and help you find what you're looking for in the Operations tree. In Coder Cloud, this is shown by default. To open this view in Coder Studio, go to the Window menu item, then select Show View > Other > General > Outline.

The Outline view in the Operations tab

The Outline view in the Operations tab