A little history...
Nearly ten years ago the Office of Information Technology (OIT) determined that our future applications should be driven by APIs based upon Web Services. Since then OIT has been heavily focused on providing APIs for use by OIT as well as campus consumers.
As part of our API initiative OIT implemented a number of technologies, including:
An APIKey infrastructure used to provide consumers access to the APIs. This solution was a BYU custom application based upon industry best practice at the time.
An API Manager (SOA Software) to help us manage the APIs we publish.
Over four hundred APIs implemented in either SOAP or REST that provide access to university resources.
OIT has been able to provide a number of innovative technologies such as the BYU Mobile Application because of the API initiative. Many others on campus also have provided APIs for campus use.
The current situation...
In order to keep up with changing technology, OIT has decided to move all BYU APIs from the current API manager, SOA Software, to a new API Manager, powered by WSO2.
Why should I care?
If you currently utilize any web service from OIT or one of our campus partners, you care. Unfortunately the migration will require some changes in your application. Depending on how your specific application is architected these changes could be small or they could be extensive. We have introduced a number of new standards and are providing a number of language specific SDKs in order to make the transition easier.
What's an API Manager anyway?
An API Manager is the central point of our API infrastructure. It provides a repository of all of our published APIs and allows us to track and manage their usage. It also provides integration with our APIKey infrastructure to secure our APIs. All access to OIT APIs goes through one of our API Managers: SOASoft or WSO2.
Our current API Manager is provided by a company called SOA Software (hence the nickname SOASoft). It has served us well for the past nine years but is now well past its expected life. Our API usage has grown to the point that we are now processing tens of millions of request per year and it's time to make some changes.
Technologies related to APIs have continued to advance. There are now standards for many aspects of API consumption that were not available when we started using APIs ten years ago. Our SOASoft infrastructure is based on a number of technologies that are now considered obsolete. Because of this, we are not able to progress in our current situation, because a number of toolkits that we need to use are not supported by SOASoft infrastructure.
What are we moving to?
OIT has chosen to change vendors and move to an API management infrastructure provided by a company called WSO2. There are many advantages to the new API Manager including much better support for industry standards such as REST, OAuth, JSON, and many others. WSO2 is also an open source company, which means we have full access to all of the source code for the products we run. This allows us to better adapt the software to our specific needs and to respond more quickly to issues with the software. We anticipate that the new software and servers will be able to handle our projected growth in usage for a number of years to come, as well as provide us the ability to leverage emerging technologies.
Our new API Manager does change things a bit. We will now require applications to be registered before they can access APIs. Application registration allows us to better track API usage and know which applications are impacted when services are having issues. It also is required for authorization to work correctly. Application registration is an easy process. Each application has its own set of access keys for production API access and a separate set of keys for sandbox API access. Once you've created an application, you can find APIs by either searching in the API Store or the Developer Portal, and then subscribe to those APIs to let us know you intend to use them. Once the API subscription is complete, you can use the API.
So what do I have to do?
There are two major changes that all applications will have to account for:
We are retiring the APIKey infrastructure and moving to OAuth 2.0. If you've ever used a third party app with Facebook or Google credentials, you have already used OAuth. OAuth provides a standard way for clients to receive a set of information about particular users after they have authenticated themselves through our CAS sign-on screen. OAuth provides a number of scenarios (called grant types) that support authorization for web based access, mobile apps or single page apps, and batch processes. OAuth uses an authorization token passed as an HTTP header to obtain access to protected services. This token is good for as many API calls as necessary and can remain valid for up to an hour. This is much more efficient than our current APIKey infrastructure, which requires a Nonce for each API call. To migrate from SOASoft to the new API Manager, you will need to begin using OAuth 2.0.
The URLs for the APIs you are using are going to change. As much as we would like to have kept the URLs the same to minimize changes to the clients calling the APIs, this just wasn't possible. For your convenience, we have provided a utility which, given an existing URL, provides the new URL. One difference you should note is that, unlike in SOASoft, production and sandbox (test) endpoints do not have different URLS. Instead, the routing of the call to production or sandbox endpoints is determined by the OAuth access keys you use to authenticate with.
The vast majority of APIs have been migrated to our new API Manager and are ready to use. We do have a small number that will not move, but are being replaced with newer APIs. Most of these APIs are SOAP based and access our financial information. You can use the migration utility to determine if an API you are using is available in the new system or is being replaced.
Anything else I should know?
If your current application has been granted extra privileges allowing for access to sensitive or otherwise restricted data, those privileges will be granted to your application in the new API Manager. There are instructions in the Developer Portal on how to let us know which application to move the privileges to.
What if I've published APIs in SOASoft for others to use?
Hopefully we have already been in contact with you about migrating your APIs. If not, please contact us at email@example.com
We've added some new goodies as well...
As part of the move to our new API Manager, we've been working on implementing some new technologies that can make coding your applications and back end services easier and more resilient to change. Some of those technologies are:
JSON Web Tokens - JSON Web Tokens are a standard way of sharing information between processes. Our infrastructure makes extensive use of JWTs for identity processing. Each JWT is digitally signed and our public keys are provided so the contents can be verified as authentic. We use JWTs on both the front end (id_tokens from OpenId Connect requests) and also to provide identity information to services being called through the API Manager.
Swagger based definitions of our APIs - Swagger is a REST API definition standard. We have provided at least basic Swagger definitions for all of our APIs. Many APIs have more robust Swagger definitions. There are many toolkits available that allow for generating code from Swagger documents.
OpenID Connect - Provides identity information back to the application as part of the login process. Your application can be provided with all three identifiers associated with the user (person_id, byu_id, and net_id), along with some basic name information, automatically after the login sequence is complete.
OpenID Connect Discovery - Provides a standard location for reading API Manager configuration information (which URL to use to get access tokens, etc) in JSON format. Also provides the public keys used to sign our JSON Web Tokens.
Events - We have been busy instrumenting our systems to raise events when business events that may be of interest, are performed. Events include address changes, classes added or dropped, and over a hundred others from a variety of systems. Events are raised and consumed through our Event Hub.
University API - The University API is a new API definition that attempts to standardize how APIs provided by OIT and others operate. This greatly simplifies the job of API consumers and insulates them from changes to underlying systems.
Are you really going to turn off SOASoft on April 30?
That is the plan. We are going to do our best to meet that date. Given the state of our SOASoft implementation we are strongly advising all of our API consumers and providers to take that date seriously.
Is there any way I can get some help?
Yes. We have set up the following training meetings to make the transition as easy as possible:
3 Web Service Trainings (For those who provide APIs)
Thursday, March 16th (9am-11am): Migrating the Timekeeper Web Service (NodeJS) (Video Coming)
3 Web Client Trainings (For those who consume APIs)
Tuesday, March 21st (12pm-2pm): Migrating the Timekeeper Web UI (NodeJS) (Video Coming)