APIs available on our developer portal use Apigee as an API gateway. Apigee proxies our API traffic to handle functionality like authorization, authentication, caching, and load balancing, among other things. Our current license with Apigee allows us 8 million API calls per month. This quota has been able to give us a comfortable amount of headroom since we started using Apigee in 2015, but since the start of this academic year, we’ve been getting too close to our 8 million limit (which is a good problem to have!). We don’t expect API traffic to slow down, so we are changing are plan with Apigee to increase our monthly quota. As apart of this upgrade, Apigee is also upgrading our gateway to use better infrastructure which is hosted on Amazon Web Services. Our new agreement with Apigee means that our monthly quota is increased to 300 million calls per month and we are getting a higher runtime SLA.

One downside to this upgrade is an outage required from Apigee. Apigee has done these types of upgrades to its other customers before, so they envision the outage to last 10-45 minutes. We have scheduled this outage on Thursday, November 2nd, at 7:00AM (please see the update below for the new upgrade date). This will be a total outage of all our APIs for api.oregonstate.edu including the development and test environments.

Apologies for any inconvenience caused from this outage, but thank you for bearing with us as we aim to improve our APIs and adapt to increasing traffic.

Update

As of 10:00AM November 2nd, all APIs are back online. The upgrade was unsuccessful for Apigee and they had to rollback the changes they were performing. This upgrade will be performed at a future date and time. Apigee identified the problem that prevented the upgrade and will be addressing it before the next upgrade. We apologize that the outage lasted longer than expected. We will be working with Apigee to make sure the future upgrade causes less interruption for API traffic.

Apigee is going to try the upgrade again on Thursday, November 9th, at 6:00PM. The problem with the previous upgrade attempt was found to be related to access tokens. Apigee was copying access tokens which was slower than normal, so they decided to abort the upgrade. For the upgrade scheduled on November 9th, Apigee is not going to copy access tokens. We decided that since most access tokens expire in an hour or less, skipping access tokens reduces the outage time and risk associated with this upgrade.

Final Update

Apigee successfully completed the upgrade and all API traffic was returned to service at 6:20PM, November 9th. Thanks for bearing with us!

One of our most popular API’s is the locations API. The locations API is used to get campus buildings, extension campus locations, and dining locations on campus. Since the word “location” can be used to describe many types of places, we actively source new locations to add to the API and discover new data to add to existing locations. While sourcing new locations and data, we work with data stewards to ensure the data we are providing is accurate and true. One example of enhancing existing locations in the API is the recent addition of building geometries to Corvallis campus buildings.

Centroids

Initially, campus buildings in the locations API included a coordinate pair in their data which represents the centroid of a building. This can be useful as an alternative to the building’s address to place a point on a map to represent the building’s location. Better yet, the coordinates can be used to query against by specifying lat and lon query parameters in the URL of a locations API request. Using these parameters queries buildings that are close to the coordinates provided in the URL. Use the distance and distanceUnit query parameters for a more specific query.

Here’s an example of a locations API request that returns all locations that are within 300 yards of the Valley Library:

https://api.oregonstate.edu/v1/locations?lat=44.56507&lon=-123.2761&distance=300&distanceUnit=yd

Geometries

Centroid coordinates are useful for performing actions related to the distance, but what if you want to draw the shape of a building on map? A new dataset we recently added to buildings is geometry coordinates. Geometry coordinates can be used with services like the Google Maps API to draw building shapes on a map. A good open source alternative to the Google Maps API is Leaflet which can also map coordinates from the locations API.

Buildings in the locations API now have a geometry object which follows the GeoJSON specification for a geometry object. Within the geometry object is type and coordinates. Type will either be Polygon or MultiPolygon, depending on the location. Locations that have multiple physical structures will be MultiPolygon (like Magruder Hall) and Polygon is for a location that only has one structure. Most buildings on campus are polygon locations.

Let’s take a closer look at a simple polygon location, Hovland Hall:

"geometry" : {
"type" : "Polygon",
"coordinates" : [ [ [ -123.281543, 44.566486 ], [ -123.281544, 44.56636 ], [ -123.281041, 44.566359 ], [ -123.281041, 44.566485 ], [ -123.281543, 44.566486 ] ] ]
}

Coordinates for a polygon location will be a 3 dimensional array of coordinate pairs, where index [0] of the 3rd level of the array will be longitude and index [1] will be latitude. The 2nd level of the array represents an array of coordinate pairs otherwise known as a ring. The 1st level of the array represents an array of rings. Each ring represents a set of coordinate pairs that, if connected to each other in order, would draw a shape of the building. As a rule of GeoJson, the first and last coordinate pairs in a ring must be identical. The example of Hovland Hall shows that it has five coordinate pairs (with the first and last being identical), which make up one ring within one polygon.

Some buildings on campus have multiple rings (multiple arrays of coordinate pairs). A polygon with multiple rings represents buildings with holes in them, like Cordley Hall. In an array of rings, the first ring represents the exterior structure of a building while any additional rings are holes (interior rings). Moreover, GeoJson specifies the wrap direction of exterior and interior rings. Wrap direction is the direction that a ring is drawn when laying out each coordinate pair on a map in order. The wrap direction of exterior rings is counterclockwise while interior rings are wrapped clockwise. However, it’s worth noting that services like the Google Maps Polygon API only care that exterior and interior rings have opposite wrap direction.

Since multipolygon locations are locations with multiple structures, their coordinates array adds another dimension to represent an array of polygons. All the same rules apply, except the coordinates array for a multipolygon will be 4 dimensional.

Do you have any ideas for data to add to the locations API? Contact us to share your ideas or visit our developer portal to register an application to try using the locations API: developer.oregonstate.edu

This year our team participated in the second annual Hackathon hosted by the Information Services department. Teams were given around 7 hours to create something before presenting their creations to all the participants and being judged on their work. Awards are given out at the end for categories like simplification, partnership, and learner experience.

Our team set out to create some custom skills for Amazon Alexa – Amazon’s virtual assistant voice service. We wanted Alexa to be able to answer questions about OSU. Our team decided to use the APIs we’ve built as the data source for some of the answers we wanted from Alexa. As apart of our project, we also had to create a new API that would function as an intermediary between the Alexa voice service and our APIs that would be providing the data. Amazon allows to either use an AWS Lambda function or HTTPS endpoint to facilitate the interaction between the Alexa service and a backend data source.

Since we opted for the HTTPS option, we had to build our API around the specific JSON schema that Alexa sends and expects to receive. Amazon provides the Alexa Skills Kit to allow developers to create a skill that has a number of intents. A skill always has an invocation name that allows the Alexa to know what skill a person is wanting to use. We decided to use “Benny” as the invocation name for our skill since the questions that Alexa would answer would all be related to OSU. Intents are the types of actions that can be performed within a skill. To trigger an intent we created, we would start by saying “Alexa, ask Benny…”. When an intent is triggered, Alexa sends a request the Alexa API we created during the hackathon. Depending on the intent, our API will call one of our backend APIs to get the data for a response. The API uses the data to create a text response that’s meant to be spoken and returns the response to the Alexa.

We used the locations API for several of the intents we created. The data in the locations API allowed us to create intents to answer questions like “what restaurants are open right now?”, “is the library open today?”, and “what resturants are close to me?”.

We used the directory API to create an intent to lookup information about people on campus. We can ask things like “what is the email address for Edward Ray?” and “what is the phone number for Wayne Tinkle?”.

Our team also created intents that used our terms API and class search API. For example, to get a list of open terms, you’d say “Alexa, ask Benny what terms can I register for?”. We also created the PAC (physical activity course) intent. When I was a student, I would often find myself looking for a random 1-2 credit class to take that fit around the rest of my schedule. The PAC classes were nice because I could do fun things like biking, running, or rock climbing. The PAC intent allows you to ask “give me a PAC class for Fall 2017 at 2:00 PM on Mondays”. Alexa will then find a random PAC class that fits into that schedule.

After the hackathon, we created a video to demo some of the intents we created with an Amazon Echo. However, you don’t need an Amazon Echo to develop and test Alexa skills. There are many applications out there that allow you to test an Alexa skill, like EchoSim.

Video Demo: https://media.oregonstate.edu/media/t/0_vqlnak06

Amazon let’s someone beta test any skill they create by linking an Alexa enabled device (like the Echo or EchoSim) to their account. Releasing a skill to be available to any Alexa device requires approval from Amazon. Since the skill we created the hackathon was a proof of concept, we didn’t submit the skill to be available on all Alexa devices, therefore the skill isn’t available to be used publicly.

Centralizing Access Token Requests

Deprecation

• POST https://api.oregonstate.edu/v1/directory/token
• POST https://api.oregonstate.edu/v1/locations/token

OAuth2

Oregon State University uses OAuth 2 for API authentication and authorization. When someone registers an application on our developer portal, they get a client ID and client secret which are used during the API request process. To access an API resource, the client ID and secret are used in a token request to the OAuth2 API: POST https://api.oregonstate.edu/oauth2/token

The response for a token request will include an access token, which is used to get access to an API and has a limited lifetime. The response will also include a token expiration time and a list of APIs the access token may be used with. A developer can then use the access token in the header of a request to access an API the token is authorized for. This process works well for public data (like the locations or directory APIs) or when only specific people/departments can use an API.

Three-legged OAuth

Deprecating our decentralized token endpoints from our APIs allows us to direct all access token requests to one API instead of each individual one. This makes things simpler, but also allows us to expand our scope of OAuth2 to more than access token requests. One of the components of OAuth is the three-legged flow which allows an end-user to grant an application permission to access certain data about the user. For example, think about how applications on the web share data with each other. Let’s say a developer created a web form and allows a user to auto-fill information from their Facebook profile. The web form directs the user to Facebook to authorize the web form application to access the user’s data. This is an example of three-legged OAuth.

Enabling three-legged OAuth allows us to expand our scope when developing APIs to deal with more confidential or sensitive data, and lets the users decide on whether an application should access data about them. As an example, think about an API that could retrieve a student’s grades. The developer or the student (user in this example) shouldn’t have access to everyone’s grades. They should only be able to access their own. A student would log in (authenticate) before deciding if the application is allowed to retrieve their grades.

For more information on the OAuth standard, go to https://oauth.net/2/

Register an application on the developer portal to get started using some of OSU’s APIs: https://developer.oregonstate.edu