Developer Groups, Site Quotas, and Rate Limits

Document created by rh0068002 on Nov 28, 2017•Last modified by mkauffman on Aug 3, 2018

Version 9Show Document

Like • Show 3 Likes3
Comment • 13
View in full screen mode

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 on your production group 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. Provide 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.

If you are an open-initiative developer please request by email to developers@blackboard.com. Provide the same information as indicated above in your request.

6 people found this helpful

Attachments

Outcomes

re31640 Dec 20, 2017 11:35 AM

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?

1 person found this helpful

Actions

Peter Love @ re31640 on Dec 20, 2017 5:00 PM

Yes, the default is currently 10k per 24 hrs and each request counts as one. You'll see this from the X-Rate headers when you start making calls.

If/when you need a higher limit for production, you can create a separate group and ask to have a higher quota for that group.

1 person found this helpful

Actions

re31640 @ Peter Love on Dec 21, 2017 4:21 AM

Thanks Peter, most helpful. What sort of range of limits might be considered reasonable when we get to production? the docs say something about a 100K limit?

Actions

moneil @ re31640 on Dec 21, 2017 9:30 AM

Hi Rob,

Generally a rate limit of 150K is a good production starting point, and this is what is used for our Open Innovation Initiative adopters.

Rate_limits for licensed Learn clients run a very broad range and are determined on a case by case basis. Rate_limit increases are driven by institution size, and application data requirements, function and frequency of operation - please file a support ticket providing the above requested information. (or if you are an Open Innovation Initiative participant - e.g. not a licensed client/partner - submit your request to developers@blackboard.com)

The 150K limit is generally a good starting place but there are some large scale institutions with more than one application, resulting in some rather demanding data requirements which require a significantly higher rate_limit.

In short we have some guiding metrics, but a 'discussion' is necessary as we move in the direction of being able to set defaults for production group rate_limits.

HTH

Cheers,

-m

Actions

re31640 Dec 21, 2017 9:56 AM

Excellent, we are managed hosted institution, so guess that comes under licenced learn?

150k sounds like plaenty, but as you say, once we start shifting other apps over, I guess it soon adds up.

Actions

moneil @ re31640 on Dec 21, 2017 10:06 AM

Hi Rob,

Yep, Managed Hosting puts you in the Licensed group.

And for those not in Managed Hosting - Self Hosted, SaaS, and Partners are the other licensed groups. :-)

cheers,

-m

1 person found this helpful

Actions

re31640 Feb 5, 2018 1:11 PM

I've been playing with the API most of today and think I might have hit the 10k limit for this 24Hrs...

Can you confirm :

{"status":429,"message":"Unauthorized"}

is the expected (429 limit reached) message

either that or something else has gone wrong... will try again tomorrow and see if reset...

I've not seen any X-Rate-Limit-Reset, X-Rate-Limit-Remaining or other rate limit stuff in the headers... not sure why?

Any ideas most gratefully received.

Actions

moneil @ re31640 on Feb 5, 2018 1:53 PM

Hi Rob,

You can inspect the headers on the request result. eg in curl add the -I parameter to the curl request and you should see the above noted headers.

Hope that helps.

Actions

re31640 @ moneil on Jul 18, 2018 5:12 PM

Do you know what the -I parameter equates to in a php call

I thought it might be:

curl_setopt($tk, CURLOPT_HEADER, true);

`and that does give some Xheader like 'X-Blackboard-product'

but not the X-Rate-Limit-Remaining I'm hoping to stick in a dashboard.

Any suggestions most welcome...

this is the block it's in:

//get authorisation bearer token - expires after 1 Hour - check if resets on calls?       
//No update function on token currently      
//include url root for calls      
$urlroot = "https://foobar.ac.uk/learn/api/public/v1/";      
$key = 'foo';      
$secret = 'bar';       
// request token      
$basic_credentials = base64_encode($key.':'.$secret);       
$tokenurl = ($urlroot."oauth2/token");      
$tk = curl_init($tokenurl);      
$response_info=curl_getinfo($tk);            
curl_setopt($tk, CURLOPT_HTTPHEADER, array('Authorization: Basic '.$basic_credentials, 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8'));      
curl_setopt($tk, CURLOPT_POSTFIELDS, 'grant_type=client_credentials');      
curl_setopt($tk, CURLOPT_RETURNTRANSFER, true);      
curl_setopt($tk, CURLOPT_HEADER, true);      
$token = json_decode(curl_exec($tk));      
$response = curl_exec($tk);             
list($headers, $body) = explode("\n\n", $response, 2);       
$headers = explode("\n", $headers);       
foreach ($headers as $header) {          
list($key, $value) = explode(':', $header, 2);          
$headers[trim($key)] = trim($value);      
}       
echo $headers['X-Rate-Limit-Remaining']; // nout      
echo $headers['X-Blackboard-product']; //yep      //print_r($headers);      
curl_close($tk);

Actions

re31640 @ re31640 on Jul 18, 2018 4:48 PM

to answer the question - it looks like I needed to do another call- other than the initial authorisation call to return the Rate headers

$modulesurl = ($urlroot."courses/externalId:".$modulecode."?fields=name,id");   
cmoduledata = curl_init("$modulesurl");   
curl_setopt($cmoduledata, CURLOPT_HTTPHEADER, array('Content-Type: application/json' , $authorization ));   
curl_setopt($cmoduledata, CURLOPT_RETURNTRANSFER, true);   
curl_setopt($cmoduledata, CURLOPT_HEADER, true);   
$moduleresult = curl_exec($cmoduledata);   
curl_close($cmoduledata);      
print_r($moduleresult);