Save 37% off PRO during our Black Friday Sale! »

J-Card API

J-Card API

Building a REST API to abstract the interface to a legacy/vendor-supplied system with Ruby on Rails


Jason Lewis

March 20, 2012


  1. A Tale of Two APIs Fred Bosworth Jason Lewis Stephen

    Kelm Johns Hopkins University
  2. 2 This Session A Tale of Two APIs This session

    will feature how Johns Hopkins University used the Blackboard Transact Service Portal beta API in conjunction with an in-house developed API to provide expanded services to the Johns Hopkins community. Some of these services include in-house developed web tools, automated data import/export methods, mobile applications for Android and iOS devices, etc. Some of the services added will be discussed, as well as how having an API can allow your institution to develop similar applications with relative ease.
  3. 3 Who We Are Fred Bosworth, Jason Lewis, Stephen Kelm

    •  Fred Bosworth came to Johns Hopkins University in the fall of 1997. Fred has spent the past 14 years working on various projects using and enhancing multiple functions of both the UNIX and Windows based Blackboard Transaction systems. Fred has experience as a Systems Administrator on Windows and UNIX servers, data networking and electronics. •  Jason Lewis is a Programmer Analyst at Johns Hopkins University who is currently developing a web interface to BbTS using Ruby and Rails. Prior to coming to JHU, he worked as a system administrator and freelance web developer, and is a frequent contributor to open-source projects. He has been using Ruby since 2006, and Blackboard since summer 2010. •  Stephen Kelm came to Johns Hopkins University during the summer of 2004. Stephen has been working part time with IDCS- Systems since January of 2010. Stephen has a background in systems administration, programming, electronics, and mechanical fabrication.
  4. 4 Before the API One year ago, we presented J-Card

    on Rails, the first custom web application we developed against BbTS. And it was good. It allowed our users to utilize TS in ways that were previously difficult, if not impossible.
  5. 5 And so we thought…

  6. 6 Expanding Our Offerings Soon our target audience grew beyond

    authorized users of the TS application. These include our customers: the students, faculty and staff of JHU. This started with J-Card Mobile and has only grown since the introduction of that product. We'll see a few of those applications later.
  7. 7 Target Platforms We knew that we wanted to launch

    the core of J- Card mobile as a mobile web application in order to target as many devices as possible with our limited development resources.
  8. 8 The Golden Rule Golden rule of software development Don't

    Repeat Yourself (DRY) Rather than repeatedly recreating our data access layer for each new app, we created a REST API that serves serialized data over HTTP(S).
  9. 9 What is an API? An Application Programming Interface is

    the interface implemented by an application which allows other applications to communicate with it. In simplest terms, an API is a carefully thought out framework that allows dissimilar applications to pass data back and forth and work with each other. API’s are generally invisible to the end user
  10. 10 API Benefits •  One common data source for heterogeneous

    applications •  Encapsulation (domain logic is contained in one place; client applications don't need to know about underlying logic) •  Security - provide a layer of separation between the Transact system itself, and the various applications that integrate with it.
  11. 11 Abstraction Working directly with the Transact database is frustrating.

    The data is spread across ~450 tables. Often, the location of data you need may not seem logical. The number one benefit of our API: Abstraction The underlying database structure no longer directly impacts the development of our applications.
  12. 12 Abstraction - Example An example of why this is

    needed: Hopkins ID’s are our unique identifier, but they are stored in a table with other unrelated data rather than the Customer table. With our API, it doesn't matter. The serialized customer object the API returns contains CDF and CDG data. In addition it is searchable on any associated data, such as Hopkins ID or JHED LID.
  13. 13 Expanding Data Another big benefit of the API is

    the ability to pair unrelated data sources to present the requested information in whatever way is useful. For example, we are able to pair any data in the Transact system with user data in JHED (our Enterprise Directory), ISIS (our Student Information System), or any other data feed we require.
  14. 14 Rapid Development Reuse of existing API calls allows us

    to quickly develop new applications as needed.
  15. 15 Other Data Sources In addition to internal data sources,

    the API allows us to wrap and quickly access external data and APIs. •  Bb API – eAccounts •  Twitter •  Foursquare •  Facebook •  Custom TIA (in development) •  Anything else that exposes an API
  16. 16 Bb API The Bb API has some functionality that

    the JHU API does not, and likely never will, implement. Using the Bb API you are able to store financial account information to make deposits to stored value accounts. At JHU we don’t want the responsibility of creating a PCI compliant interface when we can use a system that Blackboard already has available and certified as being PCI compliant.
  17. 17 Bb API The Service Portal API also provides a

    number of useful features such as: •  Balance inquiry •  Transaction history •  Card management •  Account management By providing a REST interface, Bb is able to leverage open standards to make integration with Transact much easier and more accessible than it was in the past.
  18. 18 Bb API and JHU API Interface Bb’s Service Portal

    API exposes a REST interface to their eAccounts system. But rather than programming to an externally defined interface directly, those calls can be wrapped in our API to simplify access from our client applications.
  19. 19 Portability Unlike BbRails, our administrative web tools, the API

    is implementation-agnostic; the API will generate code for itself based on the structure of the underlying database. The API can be placed on ANY Bb Transact 3.x+ installation and be brought up as functional with minor configuration. Upgrades/changes to the underlying Bb Transact system can be handled with trivial intervention in the API.
  20. 20 Nuts and Bolts – HTTP to CRUD J-Card API

    is a REST API utilizing JSON for object serialization/data transfer. The HTTP verbs map to database CRUD operations on resources. POST CREATE GET READ PUT UPDATE DELETE DELETE
  21. 21 Nuts and Bolts - Framework API stack consists primarily

    of Ruby on Rails MVC framework. Primary components are: •  Models - classes which wrap database tables. 1 instance = 1 row. Models can also wrap web-based resources (public REST API's). •  Controllers - classes which contain methods to perform actions in response to HTTP requests. •  Views – in this case, the ‘view’ is the text output in JSON (or XML) format. •  Presenters - compose data from multiple models (or 'decorate' data from a single model) in a way that makes more sense from an API design standpoint.
  22. 22 Nuts and Bolts - Authentication API exposes its own

    OAuth Provider, to authenticate client apps/devices.
  23. 23 Nuts and Bolts - Overview

  24. 24 Clients – J-Card Mobile The J-Card Mobile application allows

    cardholders to perform many self service functions. This application is currently available for iOS and Android devices. •  Card Management – Freeze/Defrost or report card Lost to have issue incremented and new card created. •  Transaction History – View current stored value balance, last 25 stored value transactions, last 25 door access transactions. •  Meal Plan – View meal plan information such as remaining meals left. •  Social – View and manage currently settings in J-Card Social. View current badges awarded and points standing. •  Price Checker – Scan UPC codes on products at “CharMar”, an on campus convenience store run by Aramark.
  25. 25 Clients – J-Card Mobile

  26. 26 Clients – J-Card Central The J-Card Central application allows

    cardholders to perform many of the same functions as J-Card Mobile though a web interface. This application was developed to meet the needs of students who still wanted self service card management, but did not own a compatible smart phone. With the additional space available through a web application we are also able to quickly relay current information and announcements. J-Card Central is currently going through it final beta testing before widespread announcement.
  27. 27 Clients – J-Card Central

  28. 28 Clients – J-Card Kiosk The J-Card Kiosk once again

    allows cardholders to perform many of the same functions as J-Card Mobile and J-Card Central. J-Card Kiosks are being developed as standalone devices that can be located in common areas throughout campus. The overall layout of the Kiosk application is similar to J-Card Central but optimized for a touch screen interface. We are currently developing several form factors for the Kiosks, including working with Blackboard to allow for custom programming of the MF4100. J-Card Kiosk is currently going through it final beta testing before widespread announcement.
  29. 29 Clients – J-Card Kiosk

  30. 30 Clients – J-Card Social J-Card Social makes using your

    J-Card on campus more exciting my adding gaming elements. Badges, achievements and points are awarded for everyday transactions performed with your J-Card. Links your J-Card to Facebook, Foursquare and Twitter to connect your card to your social life. Increases J-Card visibility and usage by encouraging competition between cardholders.
  31. 31 Clients – J-Card Social

  32. 32 Clients – Custom Windows Apps Using the API we

    were able to rapidly develop custom Windows applications accessing the data in the Transact System. •  J-Card Security Validator – Cardholders at a JHU location in Washington DC tap their FeliCa cards on a reader at the front guard desk. The user’s photo, name, affiliation and card status display on a monitor for verification by guard. •  The Price Is Right – A student group recently ran a Price is Right style game at a student lounge. We provided a Price is Right themed price checking application that provided checks based on CharMar pricing.
  33. 33 Clients – Custom Windows Apps

  34. 34 Clients – Custom Windows Apps

  35. 35 Clients – iOS Admin App Provides mobile user lookup

    and card production. Runs on iPhone and iPod Touch devices. •  Admin users can quickly lookup a user, take a new photo of the user, upload it to the Transact system and print a new card from a handheld devices. •  With user of network card printers many functions of a card office can be performed remotely at orientation or similar events.
  36. 36 Clients – iOS Admin App

  37. 37 Clients – Honey Badger Terminal Provides mobile methods of

    validating J-Cards based on user selected criteria. Allows for mobile event check-in by card swipe. Provides basic POS terminal functionality. This application uses the Linea-pro 4 reader sled attached to an iPod Touch to read information directly from the J-Card. Stored value transactions are performed using our custom TIA written into our API. This application is currently in development with some functionality available for alpha testing.
  38. 38 Clients – Honey Badger Terminal

  39. 39 Clients – Room Reservations Allows students to reserve time

    in access controlled study rooms located in the new Brody Learning Commons building. This system allows for dynamic allocation of access plans based on reservations. Other applications could include allocating access based on class schedules. This application is currently in development.
  40. 40 Conclusion As you can see the use of our

    custom API has allowed us to open up the Transact system like never before. We are able to quickly respond to the needs of the cardholders with applications and data which adds value to the J-Card system overall.
  41. 41 Final Note One final, but very important note. None

    of this would have been possible without the assistance of Blackboard. Their new attitude of openness has allowed us to open the hood on the Transact system and get to the engine.
  42. 42 Demo and Questions Demo and Questions