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/120-OpenAPI.yaml and tutorials/openapi/20-OpenAPI-Validation.apis.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>
info: {}
ip: <string>
language: groovy
method: <string>
name: <string>
openapi:
- <openapi>
path: {}
port: <int>
ssl: {}
tags:
- <string>
target: {}
test: <string>
xmlConfig: {}
api:
'$ref': <string>
description: <string>
flow:
- <flow>
host: <string>
id: <string>
info: {}
ip: <string>
language: groovy
method: <string>
name: <string>
openapi:
- <openapi>
path: {}
port: <int>
ssl: {}
tags:
- <string>
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, openapi, etc. | The name of the proxy or API. | - |
| port | false | 80 | The port Membrane listens on for incoming connections. | 8080 |
| tags | false | - | - | - |
| 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. XPath and JSONPath query the body. An empty body, or one of another media type, is evaluated as an empty document. A body that should be XML or JSON but does not parse does not match. In XPath, a comparison with a missing element is false for both | header.SOAPAction == 'https://predic8.de/city-service/get' |
Child Structure
| Element | Cardinality | Description |
|---|---|---|
| description | 0..1 | Human-readable description of the API. |
| flow | 0..* | |
| info | 0..1 | Metadata about the API that API catalogs publish, such as whom to contact. It takes precedence over the same metadata in an OpenAPI document of the API. |
| 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 a TLS context: the identity (key and certificate) presented to the peer, the certificates trusted from it, and handshake parameters such as protocol, ciphers, and client-certificate policy. Attach it to a serviceProxy/api to terminate inbound TLS, or to a target to make an outbound connection over TLS; most attributes and child elements apply to both directions, but a few - such as clientAuth and useAsDefault - only take effect on an inbound context. See tutorials/ssl-tls/10-TLS-Termination.yaml for inbound termination and tutorials/ssl-tls/20-Central-SSL-Config.yaml for sharing one ssl across several APIs via $ref. |
| 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.