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 xml2Jsonplugin. 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.