In This Document
Overview
The Blackboard Developer Portal allows you to manage use of Blackboard REST APIs and applications developed using the Blackboard REST APIs. Three features the Developer Portal manages for REST application integrations, described here, are:
- Developer Groups: RESTful applications are associated with developer groups
- Site Quotas: The number of sites which may register your RESTful application
- Rate Limits: The number of REST API requests you may make against a single server during any 24-hour period
Each of these play a role in the development, management, and delivery of your RESTful applications.
We manage site quotas and rate limits so that we can understand usage, manage future default settings, and protect Learn systems from potential oversaturation. You must track the number of sites on which your REST application is installed to know when you are nearing the site-quota you've been given. As you approach your quota, you can request an increase.
Developer Groups
You manage access to registered application information using Developer Groups. This approach allows you to manage applications from pre-release to production.
Reference: https://community.blackboard.com/docs/DOC-3336-developer-portal-and-groups
When you register, the system automatically assigns you to a group of one. You can add registered team developers. As you move through the application development lifecycle from prototype through production, you may create additional groups with specific memberships for team developer access to application settings and information.
The initial registration settings provide for a very low site quota and rate limit. You will want to request an increase before deploying your application to production sites. For more information about site quotas and rate limits, continue reading.
Site Quotas
Site quotas apply to a group. Identifying a group as a ‘production group’, e.g., YourCompanyName, provides additional control to the production group. The production group name identifies your REST App to the Learn Admin when they install your application. You need to designate a production group to qualify for production-level site quotas and rate limits. To designate one of your groups as a production follow the steps provided at the end of this document.
Site quotas are group-specific. Site quotas are cumulative across the group regardless of number of applications
You are responsible for keeping track of the sites, and the number of sites, where your Learn REST Application is installed.
When a client attempts to install your REST Application and the site quota would be exceeded, they will see this message on the Learn Admin Create Integration page: Failure: Application developer has exceeded maximum number of client installations. Please contact the developer.
Rate Limits
Rate limits are required to maintain the stability of Learn systems and for the aforementioned planning. Rate limits are for a 24-hour period. Rate limits are site specific and shared across applications registered to your production group. If you have a 100K limit and three applications, each application will use a portion of that 100K limit.
For example:
Rate limit usage may be monitored at an application level via the x-headers provided in each request:
HTTP Header | Description |
---|---|
X-Rate-Limit-Limit | The rate limit ceiling for the given group |
X-Rate-Limit-Remaining | The number of requests left for the 24-hour window |
X-Rate-Limit-Reset | The remaining window before the rate limit resets in UTC epoch seconds |
Increasing Site Quota and Rate Limits
If you are a Blackboard Partner or Licensed client when you need to increase the site quota and rate limit for your production group, please open a ticket on Behind the Blackboard.
If you are an open-initiative developer please request by email to developers@blackboard.com.
All - include the following in your request:
• Production Group name (Designate one of your groups as a production group if you haven’t. Tell us what it is here.)
• Developer email that 'owns' the production group
• Application description: What it does, and APIs used.
Thanks for this, I'm rewriting some of our code using the REST API and want to make sure I don't hit rate limits
I'll have a look at those X-Rate-Limit-Remaining calls, but to make sure I get it right it would be good to have some examples of what the data might mean.
Looking elsewhere the only figure I could find as to what the actual limit might be was here:
"https://blackboard.secure.force.com/btbb_articleview?id=kA7390000008ORDCA2&cid=5003900001yAFUDAA4
“For the duration of the technical preview we have set the rate limit on a developers suite of applications to individual institution integrations at 10,000 requests per 24 hour period. As the Technical Preview progresses we will be collecting data on usage which will be analyzed to determine Customer and third party developer production grade rate limits when the Technical Preview is lifted.”
I thought we were out of technical preview, but unsure?
If I assume 10k calls per day, and each request counts as 1 call is that a good starting place?