Setting Operation Handlers for REST API Endpoints

Overview

Connect your REST API operations to specific services or workflows implemented in your Martini package. An operation handler is the executable component—either a service or workflow—that contains your processing logic and gets triggered when clients make API requests. This powerful connection allows your existing services and workflows to be accessed via fully built REST APIs, transforming your backend logic into accessible web services.

What You Will Learn

• How to connect API operations to your services and workflows as operation handlers
• How to configure operation handlers that trigger your existing components
• How to validate that your operation handlers execute correctly through API calls
• When to use services versus workflows for different API operations

When To Use This

Use operation handler configuration when you need to:

• Expose Services and Workflows: Make your existing Martini services and workflows accessible via REST APIs
• API-Enable Components: Transform backend processing components into web-accessible endpoints
• Connect External Systems: Allow external applications to trigger your services and workflows through HTTP requests

Prerequisites

• Martini Designer installed and running
• A Martini package containing your API and handlers
• A REST API created in Martini for your package
• At least one API path with HTTP operations configured (see adding API paths and adding HTTP operations)
• A service (Create a New Service) or workflow (Create a New Workflow) ready to handle requests

Getting Started with Operation Handler Connection

Transform your backend services and workflows into API-accessible endpoints by mapping each HTTP operation to specific operation handlers in your Martini package.

1. Expand your Martini package in the Navigator.
2. Locate the API file (identified by the icon with .api file extension).
3. Double-click the file to open the API configuration editor.
4. You will be in the Operations tab by default. The tabs are located at the bottom of the editor window as horizontal text labels. The Operations tab will be highlighted or selected when active.

5. Expand a path by clicking the > (arrow) icon located to the left of each path name in the tree structure. Each path appears as a folder-like entry with an expandable arrow.

   If you don't see any paths: The API may be empty. Create your first path by right-clicking in the empty area and selecting "Add Path" or refer to adding API paths.

6. Expand an operation (GET, POST, PUT, DELETE) by clicking the > icon next to the HTTP method name. Operations appear indented under their parent path.

   If you don't see operations under a path: Right-click the path name and select "Add Operation" to create GET, POST, PUT, or DELETE methods. See setting the HTTP method for detailed instructions.

7. After expanding an operation, Locate the Handler field which appears as an empty text input box with a label "Handler:".(../http-methods(../http-methods

8. The Select Operation Handler dialog box appears where you can choose your operation handlers:

   • Search for your service or workflow by name
   • Services are identified by the icon
   • Workflows are identified by the icon

9. Select the operation handler you want to trigger and click the Select button.

Expected result: The Handler field now displays the name of your selected service or workflow. Your operation handler is now connected to the API operation and will execute when clients make HTTP requests to this endpoint.

Creating New Operation Handlers from the Dialog

If you need to create a new operation handler while configuring your API endpoint:

• Click New in the Select Operation Handler dialog
• Select Handler Type: Service or Workflow
• In the Create dialog, verify the Martini package location and enter a descriptive name for your operation handler
• Click Finish to create and automatically connect the handler

Expected result: Your operation handler is now connected to the API operation and will execute when clients make HTTP requests to this endpoint.

Choosing Operation Handler Types for API Operations

Select the appropriate type of operation handler based on your operational requirements. For detailed guidance on when to use services versus workflows, see Workflows vs Services.

Testing Operation Handler API Integration

Ensure your operation handlers execute correctly when triggered through API calls.

Getting Started with API-Triggered Operation Handler Testing

Test that your operation handlers respond properly to API requests:

1. In the API configuration editor, select the operation connected to your operation handler.
2. Right-click the operation and select Invoke in HTTP Client.
3. In the HTTP Client, verify your operation handler endpoint is correctly configured by checking the request URL.
4. Prepare test data that matches your operation handler's expected inputs.
5. Send the API request with your test data to trigger your operation handler.
6. Verify the response contains the expected results from your operation handler processing.
7. Check the execution logs to confirm your operation handler executed successfully.

Expected result: Your operation handler executes through the API call and returns the expected processing results, confirming the connection works correctly.

Troubleshooting Operation Handler Configuration Issues

Problem	Detection	Cause	Fix	Affected Versions
Unable to add request parameters	No parameter choices available in dropdown	No handler configured for operation	Ensure you have a handler configured which will automatically populate request parameter choices based on handler inputs	All versions
Unable to add response body	No response body options available	No handler configured for operation	Ensure you have a handler configured which will automatically populate response body choices based on handler outputs	All versions
Missing parameter/response options	Empty dropdowns when configuring API	Operation handler not properly connected	Configure an operation handler first - parameter and response options are generated from handler inputs and outputs	All versions

What's Next

After connecting your operation handlers to REST API operations, continue to the following configurations to complete your API setup:

Request Processing:

• Configure Parameters & Headers - Control how API request data flows into your operation handlers
• Learn to map path parameters, query strings, request bodies, and headers to your component inputs

Response Management:

• Response Handling & Mocking - Control how your operation handler results become API responses
• Set up response codes, headers, and mock responses for development and testing

Security Configuration:

• Security and Authentication - Protect your operation handler endpoints
• Configure OAuth, Basic Auth, or custom authentication to control access to your operations

Helpful Resources

Operation Handler Creation and Management:

• Creating Services - Build service operation handlers
• Creating Workflows - Build workflow operation handlers
• Services Overview - Understanding Martini services as operation handlers
• Workflows Overview - Understanding Martini workflows as operation handlers

REST API Development:

• Creating REST APIs - Complete guide to building APIs that expose your operation handlers
• Adding API Paths - Define URL structure for your operations
• Adding HTTP Methods - Configure API operations that trigger operation handlers
• API Parameters & Headers - Control data flow into operation handlers
• Response Handling & Mocking - Manage operation handler output formatting
• API Security - Secure access to operations

Community Q&A: Martini Community
Have a question? Post or search it here.