The main API configuration. Extends serviceProxy with REST and OpenAPI support and expression-based routing.

Several APIs can share one port and are told apart by host, path, or a test expression. Incoming requests are probed from the first API to the last; the first one that matches handles the request.

When openapi children are present, Membrane deploys the described API and publishes its specifications at /api-docs. The path from the OpenAPI servers field determines where the API is reachable. Requests are forwarded to the explicit target when one is configured; otherwise Membrane forwards to the host from the OpenAPI servers field. See tutorials/getting-started/80-OpenAPI.yaml and tutorials/getting-started/90-OpenAPI-Validation.yaml.

Example Configuration

# Basic path routing
 api:
   port: 2000
   path:
     uri: /products
   target:
     url: https://api.predic8.de

 ---
 # URI template routing
 api:
   port: 2000
   path:
     uri: /orders/{id}
   target:
     url: https://api.predic8.de/shop/orders/{pathParam.id}

 ---
 # Custom routing with expression
 api:
   port: 2000
   test: header.SOAPAction == 'https://predic8.de/city-service/get'
   target:
     url: https://api.predic8.de/city-service

 ---
 # OpenAPI support
 api:
   port: 2000
   openapi:
     - location: openapi/fruitshop-api.yaml
       validateRequests: true
       validateResponses: true

# Basic path routing
 api:
   port: 2000
   path:
     uri: /products
   target:
     url: https://api.predic8.de

 ---
 # URI template routing
 api:
   port: 2000
   path:
     uri: /orders/{id}
   target:
     url: https://api.predic8.de/shop/orders/{pathParam.id}

 ---
 # Custom routing with expression
 api:
   port: 2000
   test: header.SOAPAction == 'https://predic8.de/city-service/get'
   target:
     url: https://api.predic8.de/city-service

 ---
 # OpenAPI support
 api:
   port: 2000
   openapi:
     - location: openapi/fruitshop-api.yaml
       validateRequests: true
       validateResponses: true

Syntax

api:
  '$ref': <string>
  description: <string>
  flow:
    - <flow>
  host: <string>
  id: <string>
  ip: <string>
  language: groovy
  method: <string>
  name: <string>
  openapi:
    - <openapi>
  path: {}
  port: <number>
  ssl: {}
  target: {}
  test: <string>
  xmlConfig: {}

api:
  '$ref': <string>
  description: <string>
  flow:
    - <flow>
  host: <string>
  id: <string>
  ip: <string>
  language: groovy
  method: <string>
  name: <string>
  openapi:
    - <openapi>
  path: {}
  port: <number>
  ssl: {}
  target: {}
  test: <string>
  xmlConfig: {}

Attributes

Name	Required	Default	Description	Examples
$ref	false	-	Reference a component defined under components.	-
host	false	not set	Restricts to requests whose `Host` header matches one of the given hostnames. Separate multiple hostnames with spaces. The asterisk `*` matches any number of characters, including zero, for basic globbing.	predic8.de *.predic8.de
id	false	-	Identifier for this API. Overrides the auto-generated entry id used for this API in the published `apis.json` catalog; otherwise an id is derived from the API's key.	order-api
ip	false	not set	If present, binds the port only on the specified IP. Useful for hosts with multiple IP addresses.	127.0.0.1
language	false	SpEL	Expression language used to evaluate the `test` attribute.	-
method	false	*	Restricts this proxy to requests whose HTTP method (GET, POST, etc.) matches. The asterisk `*` matches any method.	GET
name	false	By default, a name will be automatically generated from the target host, port, etc.	The name as shown in the Admin Console.	-
port	false	80	The port Membrane listens on for incoming connections.	8080
test	false	-	Expression evaluated against each request; the API matches only when it returns true. Used to discriminate APIs on the same port beyond host and path, e.g. by header or method.	header.SOAPAction == 'https://predic8.de/city-service/get'

Child Structure

Element	Cardinality	Description
description	0..1	Human-readable description of the API.
flow	0..*
openapi	0..*	Deploys the API described by an OpenAPI document: the document is published under `/api-docs` and, when configured, requests and responses are validated against it.
path	0..1	Restricts to requests whose path matches, either by prefix (starts-with) or, when enabled, by regular expression. In a `soapProxy`, setting a path also rewrites the paths of SOAP requests and the service addresses in the WSDL accordingly.
ssl	0..1	Configures inbound or outbound SSL connections.
target	0..1	The backend server that requests are forwarded to after passing through the flow.
xmlConfig	0..1	XML configuration for the API, such as namespace declarations used by XPath expressions.

Can be used in

No parent elements.