REST API Tutorial
Before you start with the tutorial you should finish the Getting Started guide.
In this tutorial you'll learn the basic concepts of Membrane APIs:
- Routing
- Adding behaviour using plugins
- Request and response flow
Step 1: Routing
Membrane assigns incoming requests to APIs. The APIs process the requests and route them to backend targets. The API from the Getting Started accepted all requests from port 2000
and routed them to https://api.predic8.de
.
Now we make the routing more specific and we add a second API.
Go to the tutorial/rest
folder in a terminal window and start there Membrane.
cd tutorial/rest
./service-proxy.sh
Then open the proxies.xml
file in the same folder and add a <path>
to the API:
<api port="2000">
<path>/shop</path>
<target url="https://api.predic8.de"/>
</api>
A request to http://localhost:2000/shop/
still works. But if the path does not match an error message is returned.
❯ curl localhost:2000
{"error":"This request was not accepted by Membrane. Please check HTTP method and path."}
Next add a secound API on the same port 2000
with a different path.
<api port="2000">
<path>/shop</path>
<target url="https://api.predic8.de"/>
</api>
<api port="2000">
<path>/restnames</path>
<target url="http://www.thomas-bayer.com"/>
</api>
Requests are now routed depending on the path to different backends. The following requests should routed accordingly:
curl localhost:2000/shop/
curl "localhost:2000/restnames/name.groovy?name=Pia"
Step 2: Adding Behaviour - XML to JSON Transformation
An API can take control when a request or a response is flowing through. By adding functionality you can change the behaviour of an API and add for instance authentication or logging.
The second API we added in Step 1 returns XML.
❯ curl "localhost:2000/restnames/name.groovy?name=Pia"
<?xml version="1.0" ?><restnames>
<nameinfo>
<name>Pia</name>
<countries>
<country>Italy</country>
<country>Spain</country>
<country>Belgium</country>
...
</countries>
</nameinfo>
</restnames>
To transform the XML response body into JSON add the xml2Json
plugin to the restnames API.
<api port="2000">
<path>/restnames</path>
<xml2Json/>
<target url="http://www.thomas-bayer.com"/>
</api>
Call the API again:
❯ curl "localhost:2000/restnames/name.groovy?name=Pia"
{"restnames":{"nameinfo":{"gender":"female first name","name":"Pia","countries":{"country":[{"href":"http://www.thomas-bayer.com:80/restnames/namesincountry.groovy?country=Italy","content":"Italy"},{"href":"http://www.thomas-bayer.com:80/restnames/namesincountry.groovy?country=Spain","content":"Spain"},{"href":"http://www.thomas-bayer.com:80/restnames/namesincountry.groovy?country=Sweden","content":"Sweden"},{"href":"http://www.thomas-bayer.com:80/restnames/namesincountry.groovy?country=Finland","content":"Finland"}]},"female":true,"male":false}}}
That looks much better but to make the API more developer friendly we'll format the JSON. Add the beautifier
before the xml2Json
plugin. Why the beautifier
must come before the xml2Json
we'll discover shortly.
<api port="2000">
<path>/restnames</path>
<beautifier/>
<xml2Json/>
<target url="http://www.thomas-bayer.com"/>
</api>
Now the JSON of the response should be formated:
❯ curl "localhost:2000/restnames/name.groovy?name=Pia"
{
"restnames" : {
"nameinfo" : {
"name" : "Pia",
"countries" : {
"country" : [ {
"href" : "http://www.thomas-bayer.com:80/restnames/namesincountry.groovy?country=Italy",
"content" : "Italy"
}, {
"href" : "http://www.thomas-bayer.com:80/restnames/namesincountry.groovy?country=Spain",
"content" : "Spain"
} ]
}
}
}
}
The xml2Json
and the beautifier
are just examples. There are more plugins e.g. for OAuth2, ratelimiting or loadbalancing.
Step 3: Request & Response Flow
Messages are flowing through an request- and response flow. In Step 2 of the Tutorial we added the beautifier
and the xml2Json
plugins to the flow. In this part of the tutorial we'll learn how to position plugins into the flow.
Open the admin console at http://localhost:9000 in the browser.
Klick on /restnames:2000
and you'll see the flow for the API. A requests is received by the listener, then it flows first throgh the Beautifier
and then the xml2Json
plugin. After that the request is sent to the target backend. The response flows from the target up in the oposite way through the xml2Json
and then the beautifier
.
In this case, we want the two plugins in the response flow only. To achieve this put a response
element arround the two plugins.
<api port="2000">
<path>/restnames</path>
<response>
<beautifier/>
<xml2Json/>
</response>
<target url="http://www.thomas-bayer.com"/>
</api>
Then save the proxies.xml
file and reload the browser.
Let's add the rateLimiter
plugin to our API.
<api port="2000">
<path>/restnames</path>
<rateLimiter requestLimit="3" requestLimitDuration="PT30S"/>
<response>
<beautifier/>
<xml2Json/>
</response>
<target url="http://www.thomas-bayer.com"/>
</api>
And have a look at the admin console again. The ratelimiter
makes only sence in the requests flow, so it positions itself there automatically.
Try to call the API several times in a row. The ratelimiter
should soon kick in.