I need some help with APIs! Ok, where can I help you? Well, I have multiple systems, that we use to operate our business on a daily basis, and when we do things in one system, we need the other system to know about it, and when certain events occur we need to trigger pushes or pulls between all systems--this is how many conversations begin as the API Evangelist.
While many people think they are looking for an API solution, they are really looking for an API journey, with a little assistance from me along the way. Sure they want an API to make their world more integrated, inter-operable, automated, and real time, but in reality, they are needing to get to work unwinding a mess of legacy technical, business, and political business decisions that have been over years--this takes a journey.
Ok, so where do we get started (another common theme lately) in helping quantify the problem set, and what a journey will look like to get us closer to a solution? This post is designed to help you self assess, answer a handful of key questions, and put yourself on a path forward.
Internal Systems Inventory
What systems are involved? If this is a company-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.
- -------Copy / Repeat Below for Each System-------------
- What is the system name?
- What is the public URL of the website for the system?
- Are there API opportunities surrounding this system?
- Who is the internal owner and contact for the system?
- What is the systems used for?
- -------Copy / Repeat Above for Each System-------------
For this exercise we are going to limit this grouping to internal or on-premise systems that we 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.
External Cloud Services Inventory
Similar to the internal assessment above, what external services are involved in this solution. 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 process was in place. Let's make a list of what cloud services are involved in the API driven solution we are looking for.
- -------Copy / Repeat Below for Each Service-------------
- What is the service name?
- What is the public URL of the website for the system?
- Are there API opportunities surrounding this system?
- Who is the internal owner and contact for the system?
- What is the systems used for?
- Is the system a paid or free service?
- -------Copy / Repeat Above for Each Service-------------
It is likely that these services will have some sort of API opportunity, 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 operations.
Tools In The Toolbox
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 manifesting here:
- -------Copy / Repeat Below for Each Tool-------
- What is the tool name?
- What is the public website or repository for the tool?
- Are there API opportunities surrounding this tool?
- Who is the internal owner and contact for the tool?
- What is the tool used for?
- -------Copy / Repeat Above for Each Tool-------
Also consider including open source tooling that 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.
Identifying the Objects That Are In Play
Database folks will simply focus on the schema aspect of this, but as a database administrator with over 25 years of experience, this is more about the human side of the object vs the database resource dimension of it. When it comes to identifying the ojbects 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?
- -------Copy / Repeat Below for Each Object-------
- What is the object name?
- How many of the objects are in play?
- What are other characteristics of this object?
- -------Copy / Repeat Above for Each Object-------
These objects are the digital assets of any company, organization, institution, and individual. These are the bits & bytes you want kept in sync, so you can make decision, sell products & services, and 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 Actors Involved With The Process?
Now we are getting to the very import human aspect of this assessment. Who are the people involved in this process? I am not just talking about the developers or system administrators who will be involved, I am talking about business, 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:
- -------Copy / Repeat Below for Each Actor--------
- What is the individual or group name?
- Provide a description of each individual, or group, and their relationship and needs?
- How large are the groups of actors?
- -------Copy / Repeat Above for Each Actor-------
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 Are Being Taken?
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.
- -------Copy / Repeat Below for Each Action-------
- Short title for the action
- Provide a concise description of the action
- What systems, tools, or services are touched?
- Which objects will be play a role in the action?
- Which actors will be triggering or impacted by action?
- -------Copy / Repeat Above for Each Action-------
These actions should be n plain English--no translation need. This isn't an IT project, this is a human led process, 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 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.
