Thanks to all who participated in a lively discussion on our recent webcast: SOA in the API World - Facades, Transactions, Stateless Services . . . You can find the video & slides for the webcast here.
There were many great questions posed during our session and we didn't have time to cover all so we've written out the Q&A here. Hope this helps and as always, we'd love to continue the discussion on the API Craft Google Group.
Q: What do you think about having a single canonical model within the organization to avoid multiple representation of the data?
Greg: I think it depends on the use case. I have personally seen efforts to, for instance, “define the standard Customer Object for the whole company,” which bog down and eventually fail because, for instance, different departments treat the “customer” differently for good reasons. But that doesn’t mean that there aren’t a lot of other places where it can work.
Q: Do you think JSON will ever enjoy the validation tools that XML has (XSD, stylesheet, etc.)?
Q: How do we decide on API granularity? Does SOA principles apply directly, or do we need to modify them slightly given the "resource" focus of REST?
Greg: I think that the “API Style” that we’ve been talking about at Apigee (sometimes called “Pragmatic REST”) is a nice compromise because it gives you ways to express common patterns that developers can learn very quickly. I think that following that pattern makes your API a lot more consumable.
Q: Stateless question : Any comments on using REST w/SOAP WS-Security concepts such as digital signatures or keybased authentication for long-workflow transactions? (specifically scenario of airline ticket pricing w/repeated calls, reporting drill-down, etc.).
Greg: The kind of “state” we were arguing against was the kind that exists only in the “middleware” layer and doesn’t represent a real business entity. An airline ticket is a real business identity, with a unique ID. I don’t think that using that ID to uniquely identify a ticket in an API is a bad way to go at all - in fact I think it’s the only way. But creating a “session ID” on top of that is just additional complexity for the developer who uses the API and for the infrastructure as well. Reporting drilldown may be a different case, but even then, why not create a “report” with a “report ID” (and perhaps an inactivity timeout) that the API user can drill down on.
Q: Does it mean that every time the client wants to access the web service, the client should send the user authentication details in each and every request?
Q: How will you design something like a poker game using an API and stateless services? How do you keep the table state?
Greg: Well you’re going to need that kind of state somewhere. I’m just saying that you don’t want to insert layers of non-business-related state that are just there to make the technology work.
Q: How are you differentiating between the "outside world" and "internal"?
Greg: Good question. “Outside” in my context means “outside the company,” which could be a partner, an outside agency, a customer, or a third-party developer in an open API program. But in very large companies, the difference between these types of developers and employees from another division or site is not necessarily so big.
Q: If I want to design a GUI for my web service which is exposed for public too. Should I consider my GUI also as a third party client, if not what should be the design recommendation?
Greg: I think that’s a great architecture, yes. It means that in the future you can easily build other types of apps without a rewrite. Also, keep in mind that “web app” technology is changing and will certainly change again...
Q: For those comfortable with SOA, how do you convince them the benefits of Internal APIs?
Greg: I feel that a good API is a lot more consumable than many “SOA style” web services. I think we can make the case that an “API Style” API is a way to leverage the work that was already done to “service enable” lots of important services and data. It’s a way to make the SOA stuff you already have get reused by a much larger audience, even within the company.
Q: AS API protocols change as well, like from SOAP to REST to OData, isn't it better to publically work through facades?
Greg: Sounds good to me. I really like this HTTP-based “API Style” that we are seeing a lot but of course the industry does have a way of changing. A good facade will make it easier for you to manage that change.
Q: My architects tell me that why limit to a small subset of Internal APIs where I have a plethora of SOA Services I can tap into?
Greg: Yes, but are those SOA services usable and are they actually being adopted? An “API” approach can make them a lot more consumable.
Q: Given a large organization and there are n number of teams have developing APIs internally, is it good idea to have a single entry interface to all those internal APIs?
Greg: There are big advantages to having a single way within the company for developers to discover APIs and get whatever credentials they need to use them. It’s less important in my opinion that they all be accessed via a single “api.mycompany.com” or whatever but that doesn’t mean it’s not a good goal. For instance, if you have a common API facade infrastructure then it’s easier to enforce the same security standard, or get analytics across all the APIs.
Q: How can one justify the cost of overhead of SOA in the long run?
Greg: I think that “APIs” have succeeded because they have helped the business create new capabilities quickly. I also think that in the late 2000s the SOA movement kind of stalled out because it wasn’t showing that and of course at the same time the economy wasn’t so hot either. If you can show how APIs make it possible to build new capabilities and apps sooner, and to give customers the ability to do things they can never do before, then you’re on the right rrack.
Q: What are good documentation tools available for API documentation to get Google API kind of look and feel?
Greg: There are some nice tools available from the folks at Wornik (Swagger) https://developers.helloreverb.com/swagger/ and also from Apiary http://apiary.io/. We of course have our own API consoles as well: https://apigee.com/providers
Q: how do you recommend to reconcile mega-aAPIs and granular APIs?
Greg: Not sure, but I think it depends on how big your company is and how many different things it’s trying to expose through an API.
Q: How should a retail company with international presence approach APIs?
Greg: I’m not sure I know what makes this different from an international perspective...
Q: How do i manage transactions using the Apigee API ? If I have to make a sequence of API calls in order to, say register a subscriber, should I roll back if an API fails ? Eg. Register Subscriber -> Use third party payment provider API call. Can we have a session on this particular topic in the future?
Greg: There’s no standard in the API world for distributed transactions, and given how complex they can get I don’t know if the world is crying out to go back there. So what you’re talking about is, what’s the best way to use “compensating transactions” to handle these kinds of workloads. I do think that’s a great topic to go into some detail about in a future webcast or blog post . . .