Fork me on GitHub

{"APIs"}

The University API Journey

When it comes to a snapshot of what is going on with University APIs, my University API guide from 2015, still provides a great overview. Beyond this guide, I wanted to rehash my thoughts on where APIs can begin on campus, and make sure all my relevant talking points are fresh in my mind, and queued up for use. I will execute this story, similar to how I would kickstart any API effort on campus--role call.

Role Call: Who Are The Key Stakeholders
Who are the key actors who will be impacted by APIs, and play a role in the API life cycle? APIs mean many different things, to many different people, and most people on campus will not even know what an API is, and have an awareness of how they are already impacting their worlds, or could be adjusted to better achieve desired outcomes. Each bucket of user, and role on campus, will see APIs in the same light, so let's put a little thought into who the key stakeholders are, and what API might mean.

There will be many other stakeholders, and obviously lots of nuance to each individual and their role, but for the sake general API discussion at the higher ed level, this provides a great start. The only problem is that my assessments of what API might mean to them is pretty naive, and horribly optimistic. I think we can do better, listing out these stakeholders, and how they might see API:

These are probably a little closer to reality on the ground, and make for a more realistic conversation about how APIs will be perceived in the real world. Most people on campus are not going to care about API, they will only care about the products, services, tooling, and devices they drive. However, even within this reality, there will always be people like me, who have an illness, and are compelled to try and make content, data, and other resources more accessible, and usable across campus--so let's get busy!

Where Do We Start With APIs On Campus?
There is no easy answer to this. Depending on which bucket above you find yourself in, you will see APIs very differently, and have very different objectives. How much support, and investment in the institutional API journey you have from each of the buckets listed above, will significantly alter what you are able to do. A top down API strategy, led by campus leadership, IT, with the buy-in of faculty, administrators, and teachers, looks very different from a bottom up, outside in, often student led API strategy.

Rather than providing separate strategies for each group above, I am going to attempt to lay out a process, that might generically apply to anyone, in any of the buckets listed above, when kicking off an effort. Here is my current walkthrough for anyone on campus to apply, when thinking about how to kick of APIs on campus, no matter how big, or how small.

What Are The Campus Run Systems Used?
What systems are involved? If this is a institution-wide effort, this might be a more involved task, but if it is a single project, or objective, it will hopefully be much smaller. Regardless of scope, having a well defined inventory of the internal systems that you depend on, is pretty important stuff. Let's get to list making a list of what systems are involved in the API driven solution we are looking for.

For this exercise we are going to limit this grouping to internal or on-premise systems that are running, because it is likely they'll reflect an earlier, non HTTP-centric way of doing business (not always, but usually). Ideally there is an API already in place, or there are web services, file imports and exports, or other means information portability, but these systems will usually have to be evaluated separately from the newer, more cloud-based services, which more often have a more coherent API approach.

What Are The Cloud Services Being Put To Use?
Similar to the internal assessment above, what external services are involved in the solution we seek. Try to think of all the existing services that are used, need information pushed to it, or even possibly new services that could be put to work, if this newer API approach was in place. Let's make a list of what cloud services are involved in the API driven solution we are looking for.

It is likely that these services will have some sort of API opportunity associated with, but if not, there are often APIs right below the surface if you just ask, and in some cases, it will set into motion and API journey for the service provider as well (#winning). Knowing the services you depend on is just good for business, and having them in an organized list should be part of your regular institutional operations.

What Open Source Software Tools Are Used?
Let's do what we just did for internal systems, and cloud services, but this time for the open tooling put to work. Like internal systems don't always resemble newer cloud services, open source tooling also have different considerations, and varying ways in which they can be applied. Let's make a list of what open source tooling is involved in delivering on the API driven solution we are working to manifest here:

As with services, consider including what new open source tooling you'd like to see added to the mix. Maybe you are just looking to replace an existing internal system, or possibly a 3rd party service you are depending on, with an open source solution. Let's get to work putting together a master list of all the open tooling at play in this project.

What Are The Bits and Bytes That Are Involved?
Database folks will simply focus on the schema aspect of this, but as a database administrator with over 25 years of experience, this exercise is more about the human side of the object vs the database resource dimension of it. When it comes to identifying the objects that are in play, I'm looking for the meaningful nouns that are part of this personal, business, or other scenario being tackled as part of this project. What are all the parts and pieces being moved around like contact record, images, documents, and even down to the micro level with tags and categories?

These objects are the digital assets of any institution, organization within the institution, and individual(s). These are the bits & bytes you want kept in sync, so you can make decision, offer new services, or just operate on a daily basis. A well defined dictionary of these objects should exist, so that their storage, transmission, syndication, sharing and other aspects can be tracked in detail.

Who Are The Key Individuals Involved With API Efforts?
Now we are getting to the very import human aspect of this assessment. Who are the individuals involved in this process? I am not just talking about the developers or system administrators who will be involved, I am talking about business units, and partner stakeholders, system users, and even the operators of 3rd party API providers. Let's compile a list of who will be touched by any part of this:

These actors are the central focus of this effort, with the systems, services, tooling, and objects always playing second fiddle. Ultimately this is all about alleviating the frustrations of actors, deliver better products, services, provide support, and improve web, mobile, and other API driven applications that they are using.

What Actions Need To Be Taken As Part Of API Efforts?
The last piece of this assessment, is what actions will be taken? What are the specific actions that are needed to satisfy this effort, that is keeping systems in sync, putting internal or 3rd party APIs to use in an existing system, or possibly what is satisfied by a new API or piece of open source software. We need a list of meaningful actions you are looking for, including which of the key actors involved, putting the systems, tools, and services broken out above to work. Feel free to break them down by any logical grouping, and be sure to be as details as you feel necessary.

These actions should be in plain English--no translation need. This isn't an IT project, this is a human led effort, trying to satisfy a specific need you (they) have. You may not full understand which system, service, or tool that will apply, so focus on describing the specific goal, and need--the rest will come later. Realization of these actions is why we are doing this, and having them well documented helps ensure we can push them forward in future iterations, and integration.

This Should Provide A Basic Assessment To Get Started On The University API Journey
These are all the moving parts involved. Hopefully this outline provides you a little taste of what the actual API journey may look like. API is more about understanding the systems you depend on, the resources at play, and the consumers involved, than it really ever is about the API. An API is just the enabler, allowing us to talk through the systems, services, tooling, processes, and establish a better understanding of the transactions that need to occur, both synchronous, and asynchronously, to meet the needs of everyone involved.

Whats next? Well that depends on the completeness of this assessment, and the API opportunity that exists with the systems, services, and tools being used--not all will be conducive to integration, interoperability, and automation, for a variety of technical, business, and politics reasons. However, before we can make this assessment, we need to take a snapshot all the moving parts, and better understand what the end play might be. This should get things going, and with the detail you provide here, you (we) should be able to better communicate these needs to any 3rd party, that might be helping move things forward (I am happy to review!).

Focus On A Handful of High Value APIs First To Get Your Footing With Entire Cycle
Once you complete your assessment, you should have a pretty good list of what needs to done. Select the low hanging fruit, which are the API efforts that will require least amount of work, to get the biggest reward. Examples of this in the wild, can be scraping existing content off the website to launch APIs, or converting of spreadsheets and CSV files to APIs. These should be resources that get regularly asked for by other faculty, students, vendors, and other key stakeholders. Get the APIs up, stand up a central API portal(s), and organize your API resources, complete with documentation, support, and other essential building blocks for operating an API platform.

Next Focus On Providing Real API Driven Solutions For Consumers To Learn From
Once you have gotten your feet wet in identifying, designing, developing, and deploying an API, get to work providing real solutions, that solve everyday problems for folks on campus. Develop tooling that uses the API(s), and accomplish common tasks, develop meaningful visualizations that can be used on websites and in portals. Learn how to feed valuable, centralized, API driven data and content to be used in spreadsheets using services like Blockspring. See if their is an existing Zapier solution, that allows you to use an existing API, or common format like RSS and Webhooks to trigger useful actions. Without tooling and processes that use an API, while providing an easy to understand and execute solutions, nobody will care about an API.

Repeat, Rinse, Repeat, Rinse -- Never Stop Iterating, It Is A Never-ending Journey
APIs are not a destination, they are an ongoing journey. You will be repeating much of what is outlined as part of this story in the future. You will constantly be taking inventory of internal and external systems, identifying the common objects and items at play, and who the key actors are. The reason we do APIs is not for APIs sake. The reason we do APIs is that we learn so much throughout the process around how we use technology, who are the people and personalities, and what are the critical bits and bytes that play an important role in helping you achieve your goals.

Ideally you are beginning this journey with small steps. APIs are best done in small, bite-size iterations, and projects. The planning is small, the API is small, keeping things achievable, evolvable, and much easier to recover, when failure enters the picture. The API journey is about working to understand how technology is being used, evaluate what processes are most valuable to all the stakeholders at the table, and deliver API driven web, mobile, and device based apps that will enable these valuable process that have been identified.