Getting started

Gydro api gateway listens to port 8000 and admin api listens to port 8001.

Let's create a new api. We need to provide:

• a name (which will act as a unique identifier)
• a route for your service (it will be then available at http://localhost:8000/your_route
• One or multiple backend urls for your services (if multiple backend are specified, Gydro will provide a round-robin load balancing between them).

curl -XPOST "http://localhost:8001/apis/" -d "name=service1&route=/service1&backends=http://service1.com"

Now let's change this and add multiple backends to our api:

curl -XPATCH "http://localhost:8001/apis/service1/" -d "backends=http://service1.com&backends=http://service1-2.com"

We will now try to reach our api:

curl -XGET "http://localhost:8000/service1/"

It should returns an 401 error. It's perfectly normal. We need to create a consumer first, you only need to provide a username (which will act as a unique identifier):

curl -XPOST "http://localhost:8001/consumers/" -d "username=consumer1"

This will return your new consumer with a generated api key. If needed, you can set a custom api key:

curl -XPATCH "http://localhost:8001/consumers/consumer1/" -d "apikey=MY_CUSTOM_KEY"

Let's try to reach our api again, this time with the api key (you can pass it via GET, POST or in headers):

curl -XGET "http://localhost:8000/service1/?apikey=MY_CUSTOM_KEY"

It works!

Rate limiter

Now, you may want to limit the access of this consumer. Gydro privides a simple rate limiter that allows you to limit api calls per second (s), minute (m), hour (h) and day (d). Let's add a limit per minute:

curl -XPATCH "http://localhost:8001/consumers/consumer1/" -d "ratelimit[m]=10"

Now, try to call your api more than 10 times in a row. After the limit is reached, it will returns a 403 error.

Group based authorization

You may also want to limit access to specific apis for some users. You can do this using the simple group system. You put apis and consumers in one or multiple groups. If the consumer has one group in common with the api he's trying to reach, he'll be authorized. If the api has no group, every consumer will be able to request it.

Let's add some groups to our api:

curl -XPATCH "http://localhost:8001/apis/service1/" -d "groups=g1&groups=g2"

If we try to reach this api with our usual consumer now, you'll see a 403 error. Let's add our consumer in some groups:

curl -XPATCH "http://localhost:8001/consumers/consumer1/" -d "groups=g2&groups=g3"

Now, we can request our api normally because our consumer is in the "g2" group.