API Limits

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.

Limit Type	API “type” Parameter	Additional Required Params*
Instance	instance	N/A
User	instance.user	user_id
Each User	instance.each_user	N/A
Service	instance.service	service_id
Service By User	instance.user.service	user_id, service_id
Service by Each User	instance.each_user.service	service_id
Endpoint	instance.service.endpoint	service_id, endpoint
Endpoint by User	instance.user.service.endpoint	user_id, service_id, endpoint
Endpoint by Each User	instance.each_user.service.endpoint	service_id, endpoint
Role	instance.role	role_id

• Standard required parameters include: type, rate, period, and name.

Below is a table which describes all of the available parameters that can be passed when creating limits.