CAP API Info

From May 6, 2022:

Attention Stanford Profiles CAP API Users,

We have made several improvements to our infrastructure to reflect the state of the Stanford Profiles systems more accurately during periods of both planned and unplanned maintenance.

During major upgrades or outages of Stanford Profiles applications, the network hardware will return an HTTP 503 – Service Unavailable response status code along with an HTML body describing the situation and expected return to normal operation. The response will be returned for all requests made to cap.stanford.edu or profiles.stanford.edu domains.

During minor upgrades or outages of specific Stanford Profiles subsystems, the Apache web servers will return an HTTP 503 – Service Unavailable response status code along with an HTML body describing the situation and expected return to normal operation. The response will be returned if the specific subsystem being contacted is down for maintenance.

In addition to these improvements, we have also added response headers to all REST API requests made to the CAP API. These headers will help clients verify that their requests have reached the CAP API servers. The response headers can be used to verify that the response was NOT generated by some intermediary during a maintenance period when the CAP API was unable to respond. Upon receiving an HTTP response to a REST request, a client will receive the following additional headers:

X-API-Provider : Stanford Profiles
X-API-Service : (api/profiles or api/cap)
X-API-Version : v1

Prior to these improvements, both browsers and clients may have received HTTP 200 – OK response status codes with HTML bodies describing the maintenance event. We received reports from clients that these HTTP 200 – OK response status codes caused issues with some applications and lead to a misinterpretation of the HTML response body as a successful reply to the REST request. By improving the consistency of our error handling during maintenance events and adding specific headers to all REST responses, we hope to provide an interface that allows clients to detect and respond accordingly to Stanford Profiles maintenance periods.

CAP API REST clients should perform the following checks after receiving a response to a REST API request

• Check the HTTP status code
• Check the Content-Type response header corresponds to a JSON content type
• Check the existence of the X-API-Provider response header

Please let us know if you have any questions or concerns. You can log a ServiceNow request by going to the following link: https://stanford.service-now.com/it_services?id=sc_cat_item&sys_id=79c9e9894fb7c3009a9a97411310c7d0. If you do not have access to ServiceNow you can send your request to [email protected].