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:
- Right click on the
code
directory of thehello
package created on this page, then select New > Gloop API. - Select Publish as the Type. Click Next.
- Specify
Greet
as the name of the API, and then select New REST API as the Type. - 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:
- Click on the Operations tab.
- 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.
- 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 thename
input property from the{name}
part of the URL that will be used to invoke the service. - Click Finish.
- Click on the Operations tab.
- Click the Add Path button on the toolbar.
- 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 thename
input property from the{name}
part of the URL that will be used to invoke the service. - 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:
- Select the
/hello/{name}
path. - Click the Add Operation button on the toolbar (highlighted on the screenshot above).
- From the appearing dialog, select GET in the available HTTP methods list.
- 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.
- Double click the Value column of the Service node, and then click the button.
- Search and select the
Greet.gloop
service created here. - 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:
- Right click on any node under the
hello/{name}
GET
operation node. - Select New Parameter from the appearing context menu.
- Select PATH as the type of parameter to add, then click Next.
- 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:
- Right click on any node under the
hello/{name}
GET
operation node. - Select New Response from the appearing context menu.
- Select (200) OK as the status of the response, and enter a simple description. Click Next.
- Choose the
greeting
output property as the property which will be used as the response's content. - 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:
- Right click on the Produces node.
- Select New Produce from the appearing context menu.
- Specify the
text/plain; charset=utf-8
as the type to add. - 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:
- Right-click on the operation.
- Select Invoke in HTTP Client from the appearing context menu.
- Configure the request to be sent via the HTTP Client view
(which consists of setting the value of the
name
parameter). - Click Send to finally send the request.