Spencer Nguyen - August 15, 2017
With the release of DreamFactory 2.8 Gold, we are happy to introduce scriptable events for API Rate Limits. These events fire every time an API Rate Limit is exceeded. Along with custom scripting, you can act on the event in a number of ways, such as sending a push notification, writing to a log, updating a database, or sending a notification email. 


In this demonstration, we will set up an email template along with a MailGun service in DreamFactory. We will then create a limit exceeded event and tie it all together, so that when a limit is hit, the system will fire off an email to our DreamFactory Administrator.

Create the Email Template

For this example, we are creating a template called, “Limit Exceeded Notification” with the following template Body:

<div style=”padding: 10px;”>                                                                        
    <p>
    Dear Administrator,
    </p>
    <p>
        A limit has been exceeded on the system.
        <br/>
        Limit Name: {limit_name}
        <br/>
        Max Limit: {limit_rate}
        <br/>
        Limit Period: {limit_period}
        <br/>
    </p>
    <p>
        <cite>Thanks, your rate limit monitor</cite>
    </p>
</div>

Notice the variables in the template which give us information about the exceeded limit. These variables are available automatically to the script when the event fires. We will be passing these variables to the MailGun service from the script we will create.

Fill out the rest of the information to set up your email template such as your Subject, Recipient Email, etc. and click Save.

Screen Shot 2017-07-17 at 9.36.59 AM.png

Set Up the Mailgun Service

This blog will not go into the details of setting up your MailGun service, but for more information, navigate to Sending Email on how to set up an email service. Keep in mind also that you may choose to set up an SMS or other means of notification using the methods in this blog post as well.

Create the Event Script Using V8js

We will create our event script using V8js. The purpose of the event script will be to relay limit information to our MailGun service in order to populate the variables listed there. MailGun will handle the actual notification. The first thing we need to do is to create a payload to POST over to the MailGun service. In Event scripting, the event variable is there to provide you information on the event. You can var_dump(event) at anytime and look at the DreamFactory log file to see all of the information it contains and what information is available to you.

In our payload, we will provide the following. Note that the template variables are the keys and the event information provides the data for our template:

Screen Shot 2017-07-17 at 9.29.52 AM.png

Once we have the payload set up, all we need to do is pass it on via DreamFactory’s internal API to our my_mailgun service.

Limits and Events (The Correlation)

Top-level Limit Events

You can create a limit event that fires for each limit that gets exceeded or create one targeting a specific limit. In the Admin App, to see all the limit exceeded events available, navigate to Script -> system -> system.limit.{id}.exceeded.

Screen Shot 2017-07-31 at 1.46.08 PM.png

Notice you have an entry for {id} as well as ones for any specific limits by id. To create an event that fires for all limit exceeded conditions, choose the system.limit.{id}.exceeded (top level) selection. This event will fire for each limit hit:

Screen Shot 2017-07-31 at 1.24.09 PM.png

Specific Limit Events

Every limit you create has a specific event available to it which fires once every time the limit is exceeded. In our example, we have an instance limit covering the entire instance as well as a very specific limit which targets a db service and a user hitting that service.

Screen Shot 2017-07-17 at 10.13.01 AM-1.png

To see the events bound to these limits, you can make an API GET call to system/event. There is a lot returned here, but find the system.limit.{id}.exceeded entry:

Screen Shot 2017-07-25 at 8.36.11 AM.png

The “id” entries are the ids of the limits we have in the system available for scripting. So, if we wanted to create an event script for our db user limit, the id of the limit would simply fill in between the brackets:

system.limit.36.exceeded

Now that we have a workable script, let’s go ahead and save that script to the system.limit.36.exceeded event in the Scripts tab under system.

Screen Shot 2017-07-31 at 1.57.38 PM.png

Pulling It Altogether (Testing the Script)

For this test, I’ve logged in as the user and set the limit threshold quite low (7 hits). Other ways to test your script would be creating a script service that contains the script itself and then hitting it directly from the API.

Screen Shot 2017-07-17 at 2.07.27 PM.png

Now that the limit has been breached, the script should send an email to the Recipient on the template notifying of the breach. 

Screen Shot 2017-07-17 at 2.19.37 PM.png

And there it is! Notice that the variables have all been filled out for us based on the exceeded limit.

Where to Go From Here

Now that you’ve seen limit event scripting in action, you now can see how many options are available to you when you start combining services in this manner. You could choose to not only send an email, but also an SNS to AWS or Push notification to a specific topic. You may want to log an event to a specific log service as well. Building Limit Events in this way gives you the flexibility to do what you need to do with DreamFactory. 

Check out the community forum to discuss or let us know what you think in the comments!