API Gateway for REST, WebSockets and legacy Web Services written in Java. Featuring:
OpenAPI:
- API deployment from OpenAPI documents
- Message validation against OpenAPI
API Security:
- JSON Web Tokens
- OAuth2, API Keys, NTLM and Basic Authentication
- OAuth2 authorization server
- Rate limiting
- GraphQL, JSON and XML protection
Legacy Web Services:
- SOAP message routing
- WSDL configuration, message validation and rewriting
Other:
- Admin Web console
- Load balancing
- Message Transformation
- Embeddable reverse proxy HTTP framework for own API gateways
-
Download the binary and unzip it
-
Run
service-proxy.shorservice-proxy.batin a terminal -
Change the configuration
conf/proxies.xml
Run the samples, follow the REST or SOAP tutorial, see the documentation or the FAQ.
Try the following snippets by copying them into the conf/proxies.xml file.
Configures APIs from OpenAPI and validates messages against the definitions. Needed data like backend addresses are taken from the OpenAPI description. more...
This configuration is all you need to deploy from OpenAPI:
<api port="2000">
<openapi location="fruitshop-api.yml" validateRequests="yes"/>
</api>A list of deployed APIs if available at http:https://localhost:2000/api-doc
Click on the API title to get the Swagger UI.
Routing requests from port 2000 to api.predic8.de when the path starts with /shop.
<api port="2000">
<path>/shop</path>
<target url="https://api.predic8.de"/>
</api>Call the API by opening http:https://localhost:2000/shop in the browser.
<api port="2000" method="GET">
<request>
<template contentType="application/json" pretty="yes">
{ "answer": ${params.answer} }
</template>
</request>
<return statusCode="200"/>
</api>Call this API with http:https://localhost:2000?answer=42 . Replace <return.../> with your <target url="backend-server"/>.
Call the following APIs with this request:
curl -d '{"city":"Berlin"}' -H "Content-Type: application/json" "http:https://localhost:2000"
This template will transform the JSON input into plain text:
<api port="2000" method="POST">
<request>
<template contentType="text/plain">
City: ${json.city}
</template>
</request>
<return statusCode="200"/>
</api>Use this one to transform into JSON:
<template contentType="application/json" pretty="true">
{
"destination": "${json.city}"
}
</template>and that into XML:
<template contentType="application/xml">
<![CDATA[
<places>
<place>${json.city}</place>
</places>
]]>
</template>Using the xpathExtractor you can extract values from XML request or response bodies and store it in properties. The properties are then available as variables in the template plugin.
<api port="2000">
<request>
<xpathExtractor>
<property name="fn" xpath="person/@firstname"/>
</xpathExtractor>
<template>Buenas Noches, ${fn}sito!</template>
</request>
<return statusCode="200" contentType="text/plain"/>
</api>Use the Javascript or Groovy plugin for more powerful yet simple transformations.
<api port="2000">
<request>
<javascript>
({ id:7, place: json.city })
</javascript>
</request>
<return contentType="application/json"/>
</api>Call the API with this curl command:
curl -d '{"city":"Berlin"}' -H "Content-Type: application/json" "http:https://localhost:2000"
This script transforms the input and adds some calculations.
<api port="2000">
<request>
<javascript>
function convertDate(d) {
return d.getFullYear() + "-" + ("0"+(d.getMonth()+1)).slice(-2) + "-" + ("0"+d.getDate()).slice(-2);
}
({
id: json.id,
date: convertDate(new Date(json.date)),
client: json.customer,
total: json.items.map(i => i.quantity * i.price).reduce((a,b) => a+b),
positions: json.items.map(i => ({
pieces: i.quantity,
price: i.price,
article: i.description
}))
})
</javascript>
</request>
<return/>
</api>See examples/javascript for a detailed explanation. The same transformation can also be realized with Groovy
Dynamically manipulate and monitor messages with Groovy:
<api port="2000">
<response>
<groovy>
header.add("X-Groovy", "Hello from Groovy!")
println("Status: ${message.statusCode}")
CONTINUE
</groovy>
</response>
<target url="https://api.predic8.de"/>
</api>Create a response with Javascript:
<api port="2000">
<response>
<javascript>
var body = JSON.stringify({
foo: 7,
bar: 42
});
Response.ok(body).contentType("application/json").build();
</javascript>
</response>
<return/> <!-- Do not forward, return immediately -->
</api>Also try the Groovy and Javascript example.
Membrane offers lots of security features to protect backend servers.
The API below only allows requests with valid tokens from Microsoft's Azure AD. You can also use the JWT token validator for other identity providers.
<api port="8080">
<jwtAuth expectedAud="api:https://2axxxx16-xxxx-xxxx-xxxx-faxxxxxxxxf0">
<jwks jwksUris="https://login.microsoftonline.com/common/discovery/keys" />
</jwtAuth>
<target url="https://your-backend"/>
</api>Use OAuth2/OpenID to secure endpoints against Google, Azure AD, github, Keycloak or Membrane authentication servers.
<api port="2001">
<oauth2Resource>
<membrane src="https://accounts.google.com"
clientId="INSERT_CLIENT_ID"
clientSecret="INSERT_CLIENT_SECRET"
scope="email profile"
subject="sub"/>
</oauth2Resource>
<groovy>
// Get email from OAuth2 and forward it to the backend
def oauth2 = exc.properties.oauth2
header.setValue('X-EMAIL',oauth2.userinfo.email)
CONTINUE
</groovy>
<target url="https://backend"/>
</api>Try the tutorial OAuth2 with external OpenID Providers
Operate your own identity provider:
<api port="2000">
<oauth2authserver location="logindialog" issuer="http:https://localhost:2000" consentFile="consentFile.json">
<staticUserDataProvider>
<user username="john" password="password" email="[email protected]" />
</staticUserDataProvider>
<staticClientList>
<client clientId="abc" clientSecret="def" callbackUrl="http:https://localhost:2001/oauth2callback" />
</staticClientList>
<bearerToken/>
<claims value="aud email iss sub username">
<scope id="username" claims="username"/>
<scope id="profile" claims="username email password"/>
</claims>
</oauth2authserver>
</api>See the OAuth2 Authorization Server example.
<api port="2000">
<basicAuthentication>
<user name="bob" password="secret" />
</basicAuthentication>
<target host="localhost" port="8080" />
</api>Route to SSL/TLS secured endpoints:
<api port="8080">
<target url="https://api.predic8.de"/>
</api>Secure endpoints with SSL/TLS:
<api port="443">
<ssl>
<keystore location="membrane.jks" password="secret" keyPassword="secret" />
<truststore location="membrane.jks" password="secret" />
</ssl>
<target host="localhost" port="8080" />
</api>Limit the number of incoming requests:
<api port="2000">
<rateLimiter requestLimit="3" requestLimitDuration="PT30S"/>
<target host="localhost" port="8080" />
</api>Distribute workload to multiple backend nodes. more ...
<api port="8080">
<balancer name="balancer">
<clusters>
<cluster name="Default">
<node host="my.backend-1" port="4000"/>
<node host="my.backend-2" port="4000"/>
<node host="my.backend-3" port="4000"/>
</cluster>
</clusters>
</balancer>
</api><api port="2000">
<rewriter>
<map from="^/good-looking-path/(.*)" to="/backend-path/$1" />
</rewriter>
<target host="my.backend.server"/>
</api>Log data about requests and responses to a file or database as CSV or JSON file.
<api port="2000">
<log/> <!-- Logs to the console -->
<statisticsCSV file="./log.csv" /> <!-- Logs finegrained CSV -->
<target url="https://api.predic8.de"/>
</api>Route and intercept WebSocket traffic:
<api port="2000">
<webSocket url="http:https://my.websocket.server:1234">
<wsLog/>
</webSocket>
<target port="8080" host="localhost"/>
</api>See documentation
Integrate legacy services.
SOAP proxies configure themselves by analysing WSDL:
<soapProxy wsdl="http:https://thomas-bayer.com/axis2/services/BLZService?wsdl"/>The validator checks SOAP messages against a WSDL document including referenced XSD schemas.
<soapProxy wsdl="http:https://thomas-bayer.com/axis2/services/BLZService?wsdl">
<validator />
</soapProxy>See configuration reference for much more.