Skip to content

Overview

Concepts and Principles

Development

Overview

IDEs

API Explorer

Releases

Release Notes

TORO Integrate

Coder Studio

Coder Cloud

Bug Reports

Search

Gloop REST APIs

Along with the ability to expose Gloop services via SOAP, Gloop also allows you to create RESTful APIs which can then be exposed to your API consumers using their automatically generated Swagger and OpenAPI definitions, as well as Postman collections.

The RESTful API functionality was built with the OpenAPI initiative in mind, so many parts and fields of the REST API editor are there to help generate the definitions. As a result, it's recommended to become familiar with the Swagger specification, as well as the OpenAPI specification.

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

For further assistance, TORO Integrate logs warning messages if it finds anything that it considers incorrect with the REST API, such as invalid data or empty fields that are required.

Creating a REST API

With TORO Integrate, you can create either a new RESTful web API from scratch or generate the services and the Gloop REST API, itself, from an existing definition. Either way, to create a new RESTful web API, you must do the following steps first:

Creating a new Gloop REST API

Creating a new Gloop REST API

  1. Launch Coder's Gloop API wizard.

    1. Go to the Coder Navigator view.
    2. Right click on your target package's code folder or any of the code directories under it where you'd like your API to reside.
    3. Select New, then select Gloop API. The wizard should now appear in your screen.

    Shortcut

    In Coder Studio, you can open the Gloop API wizard by pressing and by typing api in the appearing dialog's search box.

  2. Select Publish as the type of action, then click Next.

  3. Specify the name of the API and ensure New REST API is selected; then click Finish or Next again.

Creating a new Gloop REST API from scratch is quite different from generating one from an existing definition. If you have decided to create a Gloop REST API from scratch and would like to enter the other meta-properties of your API later on (such as its description, version, terms, and others), then you may now click Finish to proceed to opening the REST API editor. Otherwise2, click Next.

Creating a REST API From Scratch

To create a new and undefined Gloop REST API, continue using the wizard and follow the steps below:

Creating a new Gloop REST API from scratch

Creating a new Gloop REST API from scratch

  1. Choose None as the source, then click Next.
  2. Enter the version, title, and license name onto their corresponding text boxes, then click Next. These will be displayed in the Swagger or OpenAPI definition.

    Auto-complete

    The license text field has an 'auto-complete' feature that suggests commonly used licenses.

  3. Enter the documentation URL and (optionally) add a description for it. Click Next.

    Markdown

    Note that as per the specifications of OpenAPI and Swagger, the description field allows CommonMark. Coder Studio also allows you to preview the markdown as you edit it. Beside the editor are six buttons. They are as follows:

    • Source view
    • Source and Preview view
    • Preview view
    • Orientation toggle (toggles the preview being beside or underneath the source while in the Source and Preview view
    • Preview back
    • Preview forward
  4. Optionally, add any tags to the API, then click Next again.

  5. Optionally, enter the path that you would like to expose via REST. Click Next.
  6. Choose a service that you would like to add to the API, then click Next.
  7. Finally, choose the HTTP request method that the operation will map to, then click Finish.

At this point the Gloop REST API editor will open and display your newly created Gloop REST API's details:

The Gloop REST API editor

The Gloop REST API editor

How do I generate REST APIs from existing definitions?

The steps for generating Gloop services and Gloop APIs from existing definitions are discussed Generating Gloop Services. This guide does not cover the topic as it is already documented in the resource linked.

The Gloop REST API Editor

The Gloop REST API editor is what you use to map your Gloop services to your REST endpoints that are to be exposed. It has extra fields to aid in populating your Swagger, OpenAPI, and Postman definitions; and it does so by splitting up parts of the definition into separate tabs, which will be explained below.

Preview your API in TORO Integrate's API Explorer while you edit!

While you're editing a Gloop REST API, you can click on the API Explorer button in the Operations tab to watch your Swagger definition come to life in the API Explorer as you edit it! Every time you save the API, Coder Studio will reload the specification into API Explorer for you.

Previewing Gloop REST APIs live in API Explorer

Source Tab

The Source tab shows the raw Gloop definition of the REST API. This information is used by both Gloop and TORO Integrate at runtime to build your APIs. This source text is read-only, but may be selected, and copied to your clipboard.

Gloop REST API editor, Source tab

Gloop REST API editor, Source tab

General Tab

The General tab is used to maintain general information about the API. The fields here map to the Info Object in the resulting Swagger or OpenAPI definition. The fields in this tab are as follows:

Field Name Description
Version Required. The version of the REST API.
Title Required. The title of the API.
Description A short description of the API. CommonMark syntax may be used for rich text representation.
Terms Of Service A URL to the terms of service for the API. Must be in the format of a URL.
Contact Name The identifying name of the contact person or organization, which will be included in the Swagger or OpenAPI definition.
Contact URL The URL pointing to the contact information. Must be in the format of a URL.
Contact Email The email address of the contact person or organization. Must be in the format of an email address.
License Name Required. The license name used for the API.
License URL A URL to the license used for the API. Must be in the format of a URL.

Gloop REST API editor, General tab

Gloop REST API editor, General tab

Documentation Tab

The Documentation tab is used to populate the External Documentation Object section of the Swagger or OpenAPI definition. The fields in this tab 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.

Operations Tab

The Operations tab is most important tab in the editor. This is where all the paths are mapped to their respective Gloop services. In Swagger or OpenAPI, these 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 helpers to make editing faster and easier.

The Toolbar

Below is a screenshot of the 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 the 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.
Enabled Enables and disables the API. If the API is disabled, it's still editable but no operations will be exposed.

Gloop REST API editor

Gloop REST API editor

Keep reading!

Since the Operations editor has many features, you can read more about it in a dedicated section further below.

Tags Tab

The Tags tab is used to maintain the tags for the Swagger or OpenAPI definitions. New tabs are added by clicking on the plus button in the toolbar, and existing tags can be deleted by clicking the 'x' button in toolbar. Alternatively, you can select a tag and press instead to delete. To edit an existing tag, simply double click on it or select one and press . The following fields will appear when editing a tag:

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

Gloop REST API editor, adding a tag in the Tags tab

Gloop REST API editor, adding a tag in the Tags tab

Security Tab

The Security tab is used for setting the API's security. This is done by limiting access to it to certain TORO Integrate users and groups only.

How to secure a Gloop API in Coder Studio

How to secure a Gloop API in Coder Cloud

Preview Tab

The Preview tab lets you see what the resulting Swagger, OpenAPI, and Postman files will look like (in JSON and YAML for Swagger and OpenAPI, too). You can use the select box on the right-hand side of the address bar to choose which version you want to preview.

Gloop REST API editor, Preview tab

Gloop REST API editor, Preview tab

The 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. This section 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.

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 APIs 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 GIF below shows all four methods, in order:

Adding REST API paths in the Gloop REST API editor

Adding REST API paths in the Gloop REST API editor

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 will assign the HTTP request methods, parameters and responses to a Gloop service. Similar to adding a path, there are four ways of adding an operation to the editor:

  • The add-operation button in the toolbar. 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 GIF below shows all four methods, in order:

Adding a new operation in the Gloop REST API editor

Adding a new operation in the Gloop REST API editor

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.

Updating services and APIs at the same time?

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.

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.

Want help on-hand?

The Operations tree contains a lot of tooltips that can help you wth your design API. Simple hover over an entry in the Path column and a tooltip will appear.

Tooltips appearing in the Operations tree

Tooltips appearing in the Operations tree

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:

  • The add-parameter button in the toolbar. 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.
  • 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 Request 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. Note that Swagger doesn't support cookie parameters. 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.

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.

Cookie request parameters are unsupported

Postman does not support cookie request parameters. If you add a cookie request parameter to your API, TORO Integrate will log a warning message whenever the Postman file is generated.

Request Bodies

When the HTTP request method supports a request body, the New Body Parameter button will be enabled in the toolbar, and the service will contain a new node called Body Parameter. To add a body parameter to a service, you can either:

  • Click the New Body Parameter button in the toolbar. When you use this method, a new body 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 that will be mapped to the request body.
  • Use the context menu in the editor, which will be visible by right clicking on a Body Parameter node, and choosing New Body Parameter.
  • Pressing in the editor.
  • Use content assist, which is triggered by pressing in the editor, and then searching for and choosing Body Parameter.

Responses

Gloop REST APIs use the Response configuration to determine which output property to write to the HTTP response, and what 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 add-response button in the toolbar. When you use this method, a new response will appear in the editor as a drop-down selection. Use the cursor keys or highlight the drop-down to choose the response code to add to the operation. Next, expand the node using the cursor keys or mouse to populate the Body field. Finally, populate the Description field as it's required in both the Swagger and OpenAPI specifications.
  • Using the context menu in the editor, which you can view by right clicking on a Parameters node.
  • Pressing in the editor.
  • Using content assist, which is triggered by pressing in the editor, and choosing Response, or an HTTP response code. The content assist will then prompt for an output property, or response code (depending which option was chosen first). If you are already on or underneath the Responses node in the editor, the content assist will also list the output properties for you.

Below is a GIF that shows how easily a response can be added to an operation using content assist.

Adding a new REST operation response via content-assist

Adding a new REST operation response via content-assist

Below the Responses node is another 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

Note that these particular headers have invalid names for use in Java and Groovy, that's why Gloop has automatically given them an alias, which you can learn about here.

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

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

Example REST APIs

The included examples package includes some REST APIs in the apis.restApi package.


  1. As long as the schema is supported by TORO Integrate 

  2. That is, if you would like to enter your new Gloop API's details now or create a Gloop REST API from an existing definition.