Frequently Asked Questions

While there are a number of subtle differences between the gateways that may result in different responses to identical requests, the most likely cause for unexpected error responses is the increased coverage and precision of AWS' Web Application Firewall (WAFV2). We've dialed back some of its restrictions to allow for a less troublesome transition, but it effectively enforces best practices that we all should already be following, so you may see some gotchas.

One you're likely to run up against has to do with user agents. A "User-Agent" request header lets the platform receiving your call identify the operating system, application, vendor, and/or version of the agent that created the request, and is often used to tailor the response as needed for that agent. According to RFC 9110 on HTTP Semantics, "A user agent SHOULD send a User-Agent header field in each request..." 

The deprecated gateway was configured more forgivingly and did not require a "User-Agent" request header, but the new one does to help sniff out "bad bots" and such. Web browsers, Postman, curl, and most language specific HTTP request libraries are set to include them by default, but you should check to make sure your application is following that convention. If you find you need to add one yourself, you should follow IETF HTTP Working Group guidelines which state that the value should be in the form "product_name/product_version" (e.g., "ACME-http_get/2.3"), but the gateway just requires a non-null value, so "*/*" will do. 

Another case we've seen quite a bit is that using outdated versions of HTTP request libraries can result in "403 Forbidden" error replies. Make sure you keep all your libraries as up-to-date as possible (not just to keep the AWS WAFV2 happy, but also to comply with UC's IS-3 Electronic Information Security policy). 

Finally, we've found an unexpected flaw in the deprecated gateway that we will not be replicating on the new one: it turns out you could use either "app-id" or "app_id" (i.e., with a hyphen or an underscore) as the header name when authenticating via headers parameters. On the new gateway you must use the underscore.

All you have to do is change the domain part of any API requests your application makes from "apis.berkeley.edu" to "gateway.api.berkeley.edu" For example, the request "GET https://apis.berkeley.edu/sis/v2/students/61889?id-type=campus-uid" should be changed to "GET https://gateway.api.berkeley.edu/sis/v2/students/61889?id-type=campus-uid". If you've set the host domain as a constant in your application code, this should be a snap!

Be sure to make this change in your pre-production test environment first and run tests that cover all of your use cases. The new gateway does have additional layers of security, including a web application firewall, so some edge cases won't work like they did on the deprecated gateway. For example, it rejects API calls that don't include the standard "Accept" and "User-Agent" header parameters (see the FAQ on requests that worked before but get error responses on new gateway for more details).

Also, since the new gateway is cloud-based, if your application is hosted in RFC1918 address space (e.g 10.0.0.0/8) you'll need to use a proxy or NAT service (see the Known Issue on RFC1918 networks for details.)

If you're having any difficulty using the new gateway, please let us know by emailing eis-support@berkeley.edu or slacking us at #api-transition-help Include what network/IP address your application is using, the app_id used, and the timeframe in which you made the troublesome requests, along with the nature of the errors you're seeing.

Any requests submitted on the old developer portal but not processed before it was deprecated have been transferred to the new portal.

Once you receive an email letting you know your request has been approved, you'll need to add a secret app_key:

1. Go to the new developer portal at https://developers.api.berkeley.edu.
2. Either click on the "Get Access" (key) icon on the home page, or click "My Account" on the header menu then "My Credentials" on the right side menu.
3. Find the credentials on the list displayed and click on their name (in the first lefthand column).
4. Scroll down past "Plans" and you'll see your new "app_id"–click on the "Create new key" button just below it.
5. Your new app_key will display at the top of the screen in a "Success" alert box. Copy the key and paste it somewhere very safe (we suggest using the LastPass Business service provided by the Berkeley IT Information Security Office). Once you dismiss the alert, you cannot recover the full key.

Please note, these credentials will only work for requests made through the new API service gateway (https://gateway.berkeley.edu), not on the deprecated one.