Learn how to configure APIs with Membrane through a set of simple, hands-on tutorials.
The 'Getting Started' tutorial takes about 15 minutes. After finishing it, you will be able to set up the API Gateway and handle common API Gateway use cases.
Complete this tutorial before moving on to the JSON or XML tutorials.
This tutorial builds on 'Getting Started'. It explains how to read, create and transform JSON data, how to use JsonPath to extract information or compute values.
If your APIs use XML as input or output, this tutorial provides useful configurations and patterns for working with XML.
Learn how to use Membrane in more advanced scenarios. Topics include path rewriting, scripting, conditions and more.
Route API traffic with Membrane, e.g. as an outgoing API gateway that controls which headers leave your network when internal clients call external APIs.
Distribute requests across backend nodes. Covers round robin, adding and removing nodes at runtime, sticky sessions, multiple balancers, and health checks.
Use Membrane as a classic HTTP forward proxy that forwards to whatever host the client's own request names, including tunneling HTTPS traffic to a TLS-protected backend.
Configure Membrane's log output, e.g. as JSON for log aggregators, and write access logs.
Run and observe Membrane in production.
Proxy a Server-Sent Events (SSE) stream and watch it in a browser-based debugger.
Proxy a WebSocket connection that pushes live data from a backend to a web page, and log every message.
Expose Membrane as an MCP server for AI clients, inspect recent API traffic, restrict MCP tools, and protect the endpoint with an API key.
Put Membrane in front of an LLM provider's chat API (OpenAI, Claude, or Gemini). Share one provider key among many clients, enforce token and model policies, and issue per-user API keys with their own token quotas.
Terminate TLS with your own certificate, share one TLS configuration between several APIs, or forward encrypted connections to the backend untouched and route them by their TLS server name.
Protect an API against common threats. Covers Basic Authentication, access control lists, and JSON/XML/GraphQL/SQL-injection protection.
Let browsers call your APIs from other origins. Covers preflight requests, and restricting origins, methods and headers.
Issue signed JSON Web Tokens and protect an API by validating them. Covers Bearer tokens, signature/expiry/audience checks, and enforcing scopes from an OpenAPI document.
Secure an API with API keys. Covers simple key validation, scope-based access control, deriving key requirements from an OpenAPI document, and storing keys in PostgreSQL or MongoDB.
Run a complete OAuth2 setup with Membrane acting as both the authorization server and the token-validating gateway. Covers client credentials, password flow, automatic token renewal, and a distributed issuer/validator setup.
If you need to integrate legacy SOAP Web Services, this tutorial provides examples and practical guidance.
Expose a legacy SOAP/WSDL web service as a REST/OpenAPI API. Covers automatic and manual per-operation conversion, how XSD constructs map to OpenAPI, and how SOAP faults become problem details documents.
Transform requests and responses between REST/JSON and SOAP/XML by hand, with templates and Groovy scripts. Covers converting REST calls to SOAP and back, JSON/SOAP array conversion in both directions, and SOAP fault handling.
Secure SOAP messages with WS-Security: add and validate a wsse:UsernameToken, a wsu:Timestamp, and a ds:Signature, and encrypt the body with XML Encryption.
Serve an OpenAPI description, validate requests against it, rewrite the server URLs it advertises
at /api-docs (automatically, or with explicit values for a deployment behind a reverse proxy), and learn the
features added in OpenAPI 3.2, such as the QUERY method.
Publish all APIs deployed on the gateway as an APIs.json catalog, with links to their OpenAPI documents, and select the listed APIs by tag.
To run the tutorials via Docker, use the run-docker.sh (Linux/macOS) or run-docker.cmd (Windows) script instead of membrane.sh.
Important: Always run the script from the directory that contains the tutorial yaml.
Ports 2000-2010, 8443 (TLS) and 9000 (admin console) are published. For a tutorial listening on another port, add it with MEMBRANE_DOCKER_OPTS, e.g. MEMBRANE_DOCKER_OPTS="-p 3128:3128" ./run-docker.sh -c 10-Forward-Proxy.yaml (Windows: set "MEMBRANE_DOCKER_OPTS=-p 3128:3128" first). JAVA_OPTS from your environment is passed on to the JVM in the container.
The commands in the tutorials work in a Linux/macOS shell and in the Windows Command Prompt (cmd). Where they differ, a tutorial shows both variants, each under its own label line.
Use the Command Prompt rather than PowerShell for the curl commands. Windows PowerShell maps curl to Invoke-WebRequest, and PowerShell does not treat \" inside a request body as an escaped quote. To start a script in PowerShell, prefix it with .\, e.g. .\membrane.cmd -c 10-First-API.yaml.
If you have questions, feedback or run into any issues, we’re happy to help. You can also join the Membrane discussions on GitHub: