Skip to content

Martini Service Registry Functions

Overview

Martini's Service Registry Functions let you discover and interact with web APIs running across a Martini cluster. Use these functions to locate any registered web API by its fully qualified name and retrieve its instance details for downstream processing, routing, and logging. By delegating service discovery to Martini's built-in cluster manager, your applications stay portable and cluster-aware without extra configuration.

What You Will Learn

  • What the Service Registry is and how it tracks web APIs across a Martini cluster
  • Which registry backends Martini supports (Local, Kubernetes, Consul)
  • How to invoke the Get Service Instance function to locate a running web API by name
  • How to map the returned service instance data model for use in services and workflows
  • Common troubleshooting steps for service lookup failures

When To Use This

Service Registry Functions are most valuable in distributed or clustered Martini deployments where web APIs run across multiple instances.

  • Use this when you need to locate a specific web API — such as a REST, GraphQL, or SOAP API — running anywhere in your Martini cluster without hard-coding its address.
  • Use this when building orchestration logic that must route requests to the correct service instance dynamically.
  • Use this when you need to confirm a web API is registered and available before invoking it, preventing silent failures in your services or workflows.
  • Use this when logging or auditing web API availability across your cluster at runtime.

Prerequisites

Before using Service Registry Functions, ensure the following are in place:

  • Martini Designer installed and running on your system.
  • A Martini package in the current workspace.
  • The target web API (for example, a REST, GraphQL, or SOAP API such as foo.bar.HelloYou) is deployed within the cluster.
  • Basic understanding of the following:

Querying Service Instances with Service Registry Functions

The Service Registry Functions interact with Martini's cluster manager to look up registered web APIs by name and return a structured serviceInstance data model you can use immediately in your integration logic. Martini supports three registry backends — Local (default), Kubernetes, and Consul — so the same function works regardless of your deployment target.

Getting Started with Service Instance Queries

The fastest way to use the Service Registry is to invoke the Get Service Instance function with a fully qualified service name. The steps below show how to look up a web API and capture its instance details.

  1. Open your service or workflow in the Martini Designer.
  2. Drag getServiceInstance from the Service Registry folder and drop it to add an Invoke step or Function node.
  3. Set the serviceName input to the fully qualified name of your target web API:
1
foo.bar.HelloYou
  1. Map the returned serviceInstance output data model to the next step. For example, pass serviceInstance.host to a logger step to capture the resolved host address:
1
logger.info("Service host: ${serviceInstance.host}")

Expected result: The function returns a populated serviceInstance data model containing the host, port, and name of the matching cluster node. The log output displays the resolved IP address or hostname of the cluster node running your web API.

Service Registry Key Terms

Familiarize yourself with these terms before working with Service Registry Functions.

Term Definition
Service Registry Martini's internal cluster-aware directory that tracks all running web API instances and their locations.
Service Instance A data model returned by the registry representing one running copy of a web API, including host, port, and scheme.
Fully Qualified Service Name The dot-separated path that uniquely identifies a web API in Martini, for example foo.bar.HelloYou.
Cluster Manager The Martini subsystem responsible for coordinating service discovery and instance tracking across nodes.
Web API A REST, GraphQL, or SOAP API that exposes logic as a callable endpoint and is the primary target for registry lookups.
Registry Backend The underlying store that Martini queries for service instance data. Supported backends are Local (default), Kubernetes, and Consul.

Service Registry Function Properties

Properties you pass to the Get Service Instance function and properties returned in the response.

Input Parameters

Property Example Value What It Controls
serviceName foo.bar.HelloYou The fully qualified name of the web API to look up in the cluster registry.

Returned Service Instance Properties (Read-only, populated by the cluster manager)

These values are automatically resolved by Martini at runtime. Use the copy icon next to any field to copy its value for use in other steps:

Property Type Example Value What It's For
instanceId String node-1-foo.bar.HelloYou Unique identifier for this specific service instance within the cluster.
serviceId String foo.bar.HelloYou The fully qualified name of the registered web API.
scheme String http The protocol scheme used to communicate with the service instance (e.g., http, https).
host String 10.0.1.42 The IP address or hostname of the cluster node running the web API.
port Integer 8080 The port on which the service instance is accessible.
secure Boolean false Indicates whether the service instance requires a secure (TLS) connection.
uri String http://10.0.1.42:8080 The fully constructed URI for directly addressing the service instance.
metadata List [] A list of key-value pairs containing additional service instance metadata.

How Service Registry Lookup Works

When you invoke a Service Registry Function, Martini queries the active registry backend — Local, Kubernetes, or Consul — to match your web API name against all registered instances. The Local registry is used by default. Here is the end-to-end lookup flow:

  1. You provide the fully qualified web API name (for example, foo.bar.HelloYou) as the serviceName parameter.
  2. The function forwards the request to Martini's cluster manager.
  3. The cluster manager queries the configured registry backend (Local, Kubernetes, or Consul) for an instance hosting that web API.
  4. On a successful match, it returns a serviceInstance object containing the node's address and service metadata.
  5. You map serviceInstance properties — such as host and port — to subsequent steps in your service or workflow.

If multiple nodes host the same web API, the cluster manager applies its selection strategy and returns one instance. The returned data model is immediately usable for logging, request routing, or conditional logic.

Integrating Get Service Instance with Martini Services and Workflows

After resolving an instance, you can use the serviceInstance output in several ways within your services and workflows:

  • Routing: Feed host and port into an HTTP Function step to construct a dynamic endpoint URL for a REST, GraphQL, or SOAP API call.
  • Logging: Pass serviceName and host to a Logger Function to record which node handled the request.
  • Conditional logic: Check whether serviceInstance is non-null before proceeding, to guard against unregistered web APIs.
  • Workflow orchestration: Use the instance details inside a Workflow to coordinate multi-service operations across your cluster.

Service Registry Benefits and Use Cases

Service Registry Functions solve the problem of hard-coded service addresses in distributed deployments. Instead of configuring a fixed URL for every web API call, you let Martini resolve the active instance at runtime against your chosen registry backend.

  • Dynamic routing: Route API calls to whichever cluster node is currently hosting a web API, without changing your logic.
  • Cluster-aware integrations: Build integrations that automatically adapt when workflows or services move between nodes or are redeployed across Kubernetes, Consul, or a local cluster.
  • Availability checks: Validate that a required web API is registered before executing downstream logic, preventing silent failures in your workflows.
  • Auditability: Capture the resolved host and port in your logs to track exactly which node handled each request.
  • Portability: The same workflow or service logic runs unchanged on single-node and multi-node clusters regardless of registry backend.
  • Reduced configuration drift: No more updating endpoint URLs when web APIs are moved or redeployed.

Troubleshooting Service Registry Issues

Common problems you may encounter when using Service Registry Functions and how to resolve them.

Problem Detection Cause Fix Affected Versions
Web API not found Function returns null or an empty serviceInstance The service name is misspelled or the web API is not started Verify the fully qualified service name and confirm the web API is in Started state in the Navigator All versions
Cluster manager unavailable Function throws a connection error at runtime The Martini instance is running in standalone mode or clustering is not configured Enable clustering in your Martini Server Runtime configuration All versions
Stale instance returned Request is routed to an offline node The cluster registry has not yet removed a recently stopped instance Restart the target web API or wait for the registry to sync; review cluster heartbeat settings All versions
Wrong host returned Request reaches an unexpected node Multiple instances are registered; the cluster manager selected an unintended node Review cluster affinity settings in Martini Server Runtime configuration All versions
Empty serviceName rejected Function throws a validation error on invocation An empty string or null was passed as serviceName Always pass a non-empty, fully qualified service name string All versions

Helpful Resources