Posts Tagged ‘SOA’

Want a successful API program? Think like a product manager.

Kin Lane, the API Evangelist, had a really good post on maturing an API program, with the not-so-brief title of “I Have An API Deployed, And A Base Presence Established, What Can I Do To Help Me Get The Word Out?” You should definitely go read that because there’s some really good advice there.

What was very clear to me is much of what Kin and others talk about is essentially turning your API into a product and applying the discipline of product management. Set goals, identify your prospects, create marketing material, highlight the success of your customers, understand your competitors, provide good support, etc. I think it’s important for the technical audience to understand that these concepts aren’t new, even though they might be new to the technical crowd. As I know from my own experience, we technologists will flock to new technology just because it’s a shiny new thing to try out.  Unfortunately, that doesn’t make for a good product strategy.  Just as a blog of mine a long time ago on communications suggested bringing a communications expert onto your IT team, it’s also a good idea to have someone with product management experience work with you on your API program efforts.

The one thing in Kin’s post that I had a slight disagreement with was his section on goals.  While his goals were valid, these are really secondary goals to what is absolutely the number one goal: revenue.  Now, I’ve read enough of his other posts that I know he gets this, but I don’t think it can be emphasized enough.  I began my career in development and have always been on the IT side of the house, and for many, many reasons that I won’t go into in this post, too many people in IT really don’t understand the revenue models of their companies.  So, if you don’t understand how your API program will impact revenue, go back and figure it out.  You may be able to charge directly for API use and fund your own operations. It may be less direct revenue, such as how Walgreens’ photo APIs eventually result in revenue through in-store photo printing, rather than a fee for API use. Growth in new users might be great, but if there isn’t a revenue model, it will eventually become a cost sink.  One only needs to look at the number of press releases about public APIs being shut down to understand the importance of this.

All in all, Kin’s post is really, really good.  It calls out a number of specific things to do when your product is an API, so follow these things but also complement your efforts with some general purpose product management knowledge and you’ll be in a position to make good decisions.

API Design: Compartments

I’ve been reviewing the FHIR (Fast Healthcare Interoperability Resources, specification and they have an interesting concept called a compartment.  Per the spec:

Each resource may belong to one or more logical compartments. A compartment is a logical grouping of resources which share a common property. Compartments have two principal roles:

  • Function as an access mechanism for finding a set of related resources quickly
  • Provide a definitional basis for applying access control to resources quickly

Let’s look at these statements one at a time. First, the component concept provides an access mechanism for finding related resources. One very common compartment in the specification is Patient. Other resources, like Condition, clearly have a relationship with Patient. So, if I want to find all conditions that a particular patient has, I actually have two paths for doing this.

  • GET /Patient/[id]/Condition
  • GET /Condition/?patient=[id]

[id] is the unique identifier in question. In this case, both of these requests should return the same thing.  But it’s not quite that simple.  Take another resource, Communication, which deals with secure messages sent as part of patient care.  In this case, we have:

  • GET /Patient/[id]/Communication
  • GET /Communication/?subject=[id]
  • GET /Communication/?sender=[id]
  • GET /Communication/?recipient=[id]

The first example returns any communication that involves the identified patient, whether to, from, or about.  The Communication specific inquiries only allow for inquiry by the attribute of the resource where a Patient identifier can be specified.  It just so happens that in the earlier case, the relationship within Condition is represented in a patient attribute.

Independent of whether you think this is a good or bad thing, this approach where there are two ways of getting to the same resources creates a decision point for the organization.  In a large enterprise, it’s entirely possible that the implementation for different resources may be handled by different teams.  With two (or more) different ways of doing this, it creates the risk of two (or more) different implementations.  It also creates a situation where a resource that can be a compartment needs to make sure that any time a new related resource is defined and implemented, they also need to make a modification to provide the compartment-based inquiry.  Once again, if this is a separate team, this means coordination. Anyone who’s worked in an enterprise knows that the more teams that get involved, the more challenging it becomes.  

These are not insurmountable difficulties by any stretch of the imagination.  In the case of the implementation, the compartment resource should simply act like a façade and make the appropriate calls to the resource (i.e. the implementation of the first URL in the examples above simply turns around and makes the call(s) below them to complete the inquiry, such as Patient calling Condition, or Patient calling Communication).  In the case of the coordination, that’s a matter of education and oversight to make sure it happens.  The greater risk is probably that too many things get defined as a sub-structure within the compartment resource, rather than defined as standalone resources.  This can be avoided by recognizing when a proposed resource has multiple compartments.  Take the following requests:

  • GET /Practitioner/[id]/Condition
  • GET /Condition?asserter=[id]

These inquiry would give me a collection of all conditions that a particular practitioner has ever dealt with.  If Condition  wasn’t a standalone resource, and instead a sub-structure within Patient, how would I go about forming this query?  It can be done, but it’s probably not going to look as simple as what is shown above. This is where I see the hidden strength of this compartment concept.  By recognizing where we can have multiple ways of organizing a particular collection of data and traversing relationships, we can then make good design decisions on what our resources should be.

Finally, FHIR also mentions that the compartment concept can also play a role in access control.  I haven’t dug into this one as much, but I think it may have some potential. The challenge lies with data that really has multiple owners.  As a patient, I may want to use an OAuth model to grant access to my health records to a mobile app I’ve downloaded. My doctor may want to do the same thing for an application he or she uses as part of my care.  The compartment approach could give independent access paths for each of these channels with their own policies.  Again, I need to give this one more thought, but I can definitely understand why HL7 put the bullet point about access control in their specification.

What are your thoughts about this notion of compartments?  Good thing? Bad thing?  Have you implemented a similar approach? What were the pros and cons of it?  Let’s start the discussion.


Microservices Architecture versus SOA

TechTarget has published another one of my “Ask the Expert” columns.  In this one, I offer up my thoughts on the differences between a Microservices Architecture and a SOA.  In a nutshell, I think the microservices trend has moved things in the right direction, a direction that many of the SOA pundits were espousing back in the mid-2000’s.  Regardless of what we were saying, however, there’s no denying that the reality of SOA back then was still more of service enabled architecture then service oriented architecture.  Give my thoughts a read, and feel free to post comments and questions in the discussion section over there. 

Corporate Facebook Apps

CNet ran this story yesterday on Pizza Hut’s new Facebook application. They generally panned the application, but I, for one, was glad to see a corporation trying to leverage this platform. Think about it. Pizza and college students go hand-in-hand. Facebook was originally designed for college students, so if a pizza company wants to target a key demographic, why not build a Facebook application? If it is simply an embedded version of their web page, as long as it makes it even easier for those college students to order pizza, they’ve accomplished their goal. Don’t get me wrong, if it has poor usability it will fail. But the fact that it simply allowed Facebook users to order pizza and did not include “additional social features … to enhance the experience” isn’t a problem, in my opinion. I do agree that the forced friend notification is bad, but an optional one could be good. Once again, if the target demographic is college students, the intent is to tell friends that “pizza is available at my place, head on over!” All in all, however, it is the goal of Pizza Hut to sell pizza. Let Facebook provide the social aspects, let Pizza Hut provide the pizza.

What really interests me, however, is the notion of Facebook as a platform for reaching desired demographics. Previously, companies tried to “build communities” via their Internet presence. This is problematic because the company’s primary goal is to sell product, not build community. It simply makes sense to leverage these web properties whose primary purpose is to build communities and augment them with apps/widgets/whatever that can fulfill the primary purpose of your company, like selling more pizza. As a result, if you have a demographic that is likely to leverage these online communities, you need to be thinking about your architecture and how you can easily support the new “channel” of online communities like Facebook.

More on Decision Rights

Nick Malik posted this response to my previous post on governance and decision rights. In it, Nick claims that what I posted was a workable set of decision rights, which I partially agree with. He made three comments on quotes from my post, and it is the third where I disagree. He stated:

“If we focus on creating policies” — And here really is the confusion. What are those policies called? They are called “decision rights.”

While a policy can be statement of decision rights, such as “All solution architectures for projects costing more than $X must be approved by Enterprise Architecture,” they don’t have to be and I argue that the majority shouldn’t be. A policy like “All services must be entered into the registry/repository at the time they are identified.” is not a decision right, rather, it is a statement of expected behavior. If followed (in conjunction with other policies), the expectation is that the goals will be achieved, such as reduced redundant implementations of business logic. If goals aren’t reached, you need to revisit policies and processes, or even the people involved.

Decision rights are certainly part of governance, but a view that makes them the defining part is wrong, in my opinion. If we focus too much on decision rights and not enough on decisions, we are at risk of creating fiefdoms of power that perpetuate the negative, command and control view of governance. If we focus on policies that enable anyone to make the correct decisions, I think that is a better position for success.

Shameless plug: Want to learn more on SOA Governance? Check out my book by the same name, available now for pre-order and generally available in late October 2008.


This blog represents my own personal views, and not those of my employer or any third party. Any use of the material in articles, whitepapers, blogs, etc. must be attributed to me alone without any reference to my employer. Use of my employers name is NOT authorized.