API Limits
Contents
DreamFactory API Rate Limiting
DreamFactory limits can be set for a specific user, role, service, or endpoint. Additionally, you can set limits for each user, where every user will get a separate counter. Limits can be created to only interact with a specific HTTP verb, such as ‘GET’ or you could create another limit for a POST to a specific service. Endpoint limits also provide yet another powerful way to restrict at a granular level within your DreamFactory instance.
Limits Hierarchy
Limits can be created to cover an entire instance or provide coverage down to a specific endpoint. When limits are combined, a type of limits hierarchy is created where the broader limits can sometimes override the more granular ones. Take for example a limit created for the entire instance with 500 hits per minute. If a limit is created for a specific service for 1,000 hits per minute, the instance limit would issue a 429 HTTP (over limit) error at 500 hits within a minute, so the service limit would never ever reach 1,000. Make sure to keep the big picture in mind when creating multiple limits and planning your limits strategy. Set the more broad-based limit types at an appropriate level to the more granular ones.
Limit Types
Each API limit is based on a specific period of time when the limit expires and resets. Options here are configurable and include minute, hour, day, 7-day (week), and 30-day (month). The variety of limit types in combination with limit periods allows for a wide range of control over your instance. The following table provides an overview of the different types of limits available.
| Limit Type | Description |
|---|---|
| Instance | Controls rate limiting over the entire instance to include all services, roles, and users. Limit counter here is cumulative, regardless of user, service, etc. |
| User | Provides rate limit control to a specified user. In the case where both a User limit and an Each User limit is set, the user-specific limit will override Each User in terms of rate. However, both counters will still increment. |
| Each User | Sets a rate limit for each user. The main difference between this and the entire instance is that every user gets a separate counter. |
| Role | Enable rate limiting by a specified role. |
| Service | Enable rate limiting by a specified service. |
| Service by User | Enable rate limiting for a specific user on a specific service. |
| Service by Each User | Enable rate limiting for each user on a specific service. |
| Endpoint | Enable rate limiting by a specified endpoint. |
| Endpoint by User | Enable rate limiting for a specific user on a specific endpoint. |
| Endpoint by Each User | Enable rate limiting for each user on a specific endpoint. |
Limit Periods
Limit periods include minute, hour, day, 7-day (week), and 30-day (month). The limit period determines how long the limit remains in effect until automatically resetting after the period has expired.
Limits via API
Like all other services in DreamFactory, limits can be managed via api alone, provided that the user has the appropriate permissions to the system/ resource. Limits can be managed from the following endpoints:
api/v2/system/limit - Endpoints to manage CRUD operations for limits. api/v2/system/limit_cache - Endpoints to check current limit volume levels and reset limit counters manually.
Creating Limits
Limits are created by sending a POST to /api/v2/system/limit. To create a simple instance limit, POST the following resource to the endpoint:
These are the minimum required parameters to create a limit. If you pass a ?fields=* with your post, you will receive back all possible fields for the endpoint in addition to the id of the created limit as well as the timestamps when it was created.
Not passing the fields=* will result in just a resource id for each limit created. To create multiple limits in a batch mode, you can pass multiple limit objects in the resource array. As you can see, there are a lot of potential parameters you are able to pass. The following table will help with what is required for each limit type.
