Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/membrane/service-proxy
API gateway for REST, OpenAPI, GraphQL and SOAP written in Java.
https://github.com/membrane/service-proxy
api api-gateway authentication http-proxy java oauth2 proxy rest reverse-proxy ssl
Last synced: 3 months ago
JSON representation
API gateway for REST, OpenAPI, GraphQL and SOAP written in Java.
- Host: GitHub
- URL: https://github.com/membrane/service-proxy
- Owner: membrane
- License: apache-2.0
- Created: 2012-10-22T09:39:24.000Z (about 12 years ago)
- Default Branch: master
- Last Pushed: 2024-03-26T05:57:03.000Z (8 months ago)
- Last Synced: 2024-03-26T20:08:14.819Z (8 months ago)
- Topics: api, api-gateway, authentication, http-proxy, java, oauth2, proxy, rest, reverse-proxy, ssl
- Language: Java
- Homepage: https://membrane-api.io
- Size: 45.3 MB
- Stars: 440
- Watchers: 43
- Forks: 137
- Open Issues: 40
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# API Gateway
[](https://github.com/membrane/service-proxy/releases/latest)
[](https://raw.githubusercontent.com/membrane/service-proxy/master/distribution/router/LICENSE.txt)
API Gateway for REST, WebSockets and legacy Web Services written in Java. Featuring:
**OpenAPI:**
* API [Deployment from OpenAPI](https://www.membrane-api.io/openapi/configuration-and-validation)
* [Message validation](distribution/examples/openapi/validation-simple) against OpenAPI and JSON Schema
**API Security:**
* [JSON Web Tokens](#json-web-tokens)
* [OAuth2](https://www.membrane-soa.org/service-proxy/oauth2-provider-client.html), [API Keys](distribution/examples/api-management), [NTLM](distribution/examples/ntlm)
and [Basic Authentication](https://www.membrane-soa.org/api-gateway-doc/current/configuration/reference/basicAuthentication.htm)
* [OAuth2 authorization server](https://www.membrane-soa.org/service-proxy-doc/4.8/security/oauth2/flows/code/index.html)
* [Rate limiting](#rate-limiting)
* GraphQL-, JSON- and XML protection
**Legacy Web Services:**
* [SOAP message routing](#soap-web-services)
* WSDL configuration, [message validation](#message-validation-against-wsdl-and-xsd) and rewriting
**Other:**
* Admin Web console
* [Load balancing](#load-balancing)
* [Message Transformation](#message-transformation)
* Embeddable reverse proxy HTTP framework for own API gateways
# Getting Started
## Java
1. Make sure Java 17 or newer is installed.
2. Download the [binary](https://github.com/membrane/service-proxy/releases) and unzip it.
3. Run `service-proxy.sh` or `service-proxy.bat` in a terminal
4. Open http://localhost:2000 to access https://api.predic8.de over the gateway.
5. Change the configuration in `conf/proxies.xml`
## Docker
```
$ docker run -p 2000:2000 predic8/membrane
```
Browse to http://localhost:2000 or use curl:
```
curl http://localhost:2000
```
This should yield the same response as calling https://api.predic8.de does.
### Changing the Configuration
Bind a custom `proxies.xml` to Membrane container.
**Windows/Linux:**
```
docker run -v proxies.xml:/opt/membrane/conf/proxies.xml -p 2000:2000 predic8/membrane
```
**Mac:**
```
docker run -v "$(pwd)/proxies.xml:/opt/membrane/conf/proxies.xml" -p 2000:2000 predic8/membrane
```
More about setting up [Membrane for Docker](https://membrane-api.io/deployment/#docker).
## Next Steps
See the snippets below, run the [samples](distribution/examples#readme), follow the [REST](https://membrane-api.io/tutorials/rest/)
or [SOAP](https://membrane-api.io/tutorials/soap/) tutorial or have a look at the [documentation](https://www.membrane-soa.org/service-proxy-doc/).
# Configuration
Try the following snippets by copying them into the `conf/proxies.xml` file.
## Using OpenAPI for Configuration & Validation
Configures APIs from OpenAPI and validates messages against the definitions. Needed data like backend addresses are taken from the OpenAPI
description. [See the example](distribution/examples/openapi)
This configuration is all you need to deploy from OpenAPI:
```xml
```
A list of deployed APIs is available at `http://localhost:2000/api-docs`
Click on the API title to get the Swagger UI.
## REST and HTTP APIs
Routing requests from port `2000` to `api.predic8.de` when the path starts with `/shop/v2/`.
```xml
/shop/v2/
```
Call the API by opening `http://localhost:2000/shop/v2/` in the browser.
# Instrumentation
## Open Telemetry
Using the `openTelemetry` plugin and the `W3C` propagation standard, we can integrate Membrane into OpenTelemetry traces.
Membrane together with a backend with database connection.
```xml
```
See the [opentelemetry example](./distribution/examples/opentelemetry)
# Message Transformation
## Create JSON from Query Parameters
```xml
{ "answer": ${params.answer} }
```
Call this API with `http://localhost:2000?answer=42` . Replace `` with your ``.
## Transform JSON into TEXT, JSON or XML with Templates
Call the following APIs with this request:
```
curl -d '{"city":"Berlin"}' -H "Content-Type: application/json" "http://localhost:2000"
```
This template will transform the JSON input into plain text:
```xml
City: ${json.city}
```
...into JSON:
```xml
{
"destination": "${json.city}"
}
```
...and into XML:
```xml
${json.city}
]]>
```
### Transform XML into Text or JSON
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.
```xml
Buenas Noches, ${fn}sito!
```
See: [message-transformation examples](./distribution/examples/message-transformation)
## Complex Transformations using Javascript or Groovy
Use the Javascript or Groovy plugin for more powerful yet simple transformations.
```xml
({ id:7, place: json.city })
```
Call the API with this curl command:
```
curl -d '{"city":"Berlin"}' -H "Content-Type: application/json" "http://localhost:2000"
```
## Transformation with Computations
This script transforms the input and adds some calculations.
```xml
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
}))
})
```
See [examples/javascript](distribution/examples/javascript) for a detailed explanation. The same transformation can also be realized with [Groovy](distribution/examples/groovy)
## Beautifier
You can beautify a JSON or XML using the `` plugin.
```xml
baz
]]>
```
Returns:
```xml
baz
```
# Branching and Conditionals
Conditionally modify response:
```xml
exc.getResponse().setBodyContent("Example".getBytes())
```
Check if certain scopes/roles are provided:
```xml
```
# Writing Extensions with Groovy or Javascript
Dynamically manipulate and monitor messages with Groovy:
```xml
header.add("X-Groovy", "Hello from Groovy!")
println("Status: ${message.statusCode}")
CONTINUE
```
Create a response with Javascript:
```xml
var body = JSON.stringify({
foo: 7,
bar: 42
});
Response.ok(body).contentType("application/json").build();
```
Also try the [Groovy](distribution/examples/groovy) and [Javascript example](distribution/examples/javascript).
# Security
Membrane offers lots of security features to protect backend servers.
## JSON Web Tokens
The API below only allows requests with valid tokens from Microsoft's Azure AD. You can also use the JWT validator for other identity providers.
```xml
```
## OAuth2
### Secure an API with OAuth2
Use OAuth2/OpenID to secure endpoints against Google, Azure AD, GitHub, Keycloak or Membrane authentication servers.
```xml
// Get email from OAuth2 and forward it to the backend
def oauth2 = exc.properties.oauth2
header.setValue('X-EMAIL',oauth2.userinfo.email)
CONTINUE
```
Try the tutorial [OAuth2 with external OpenID Providers](https://membrane-soa.org/api-gateway-doc/current/oauth2-openid.html)
### Membrane as Authorization Server
Operate your own identity provider:
```xml
```
See the [OAuth2 Authorization Server](https://www.membrane-soa.org/service-proxy-doc/4.8/oauth2-code-flow-example.html) example.
## Basic Authentication
```xml
```
## SSL/TLS
Route to SSL/TLS secured endpoints:
```xml
```
Secure endpoints with SSL/TLS:
```xml
```
## Rate Limiting
Limit the number of incoming requests:
```xml
```
# Load balancing
Distribute workload to multiple backend nodes. [See the example](distribution/examples/loadbalancing)
```xml
```
# Rewrite URLs
```xml
```
# Log HTTP
Log data about requests and responses to a file or [database](distribution/examples/logging/jdbc-database) as [CSV](distribution/examples/logging/csv)
or [JSON](distribution/examples/logging/json) file.
```xml
```
# Websockets
Route and intercept WebSocket traffic:
```xml
```
See [documentation](https://www.membrane-soa.org/service-proxy-doc/4.8/websocket-routing-intercepting.html)
# SOAP Web Services
Integrate legacy services.
## API configuration from WSDL
SOAP proxies configure themselves by analysing WSDL:
```xml
```
## Message Validation against WSDL and XSD
The _validator_ checks SOAP messages against a WSDL document including referenced XSD schemas.
```xml
```
See [configuration reference](https://membrane-soa.org/api-gateway-doc/current/configuration/reference/) for much more.