With the up coming Fellowship One RESTful API we wanted to take the some time and look back on our other two APIs and reflect on what we intended them to be and what they actually became. We looked at the their interfaces, authentication, resources, versioning, protocols, logging mechanisms, "debuggability", etc... What we found out was that in the world of "API" nothing ever ends up like you intend.
Fellowship One Data Exchange: A very powerful XML RPC API that was specifically designed to address massive data import and export needs. It's ridged pinpoint interface allow users to build simple data presses, which move large amounts of data between disparate systems. A few years into the product's life we introduced the ability to do synchronous transactions - a decision that completely changed many consumer's usage patterns.
Serendipity
stepped in and instantly consumers began to use this brute force
application on websites to perform anything from profile updates to
seamless login patterns. After seeing how much the community found value in the login metaphor we've published docs and given presentations on the best practices of this approach. We now have 3rd parties writing web
applications and hosting web sites that do a myriad of things.
Being a SOAP based .NET web service, consuming Data Exchange required the language to either have a library that constructs SOAP envelopes or that the developer understand that protocol and be able to construct a SOAP message manually.
Another characteristic of this API are the logging and response mechanisms; both were intended to only be used / interpreted by the consuming application. Its authentication is based on simple credential / key maps.
Fellowship One Payment Gateway: A .NET SOAP based web service that gives churches the ability to submit giving / e-commerce transactions. The interesting thing about this service is that it was originally developed for internal consumption only and later opened up to external consumers for book stores, tithe applications, etc... another decision point that changed the way an established API was used.
Payment Gateway answered a changeling question of: "how do I get all of my billing and payments to go through one channel and be able to report on the transactions going through that channel?" Much like Data Exchange, we saw it consumed in ways we couldn't have imagined.
We used credential and signed key authentication for this API.
Fellowship One RESTful API: A REST based web application that uses several open protocols and patterns to provide consumers access to secure resources.
STANDARDS, PROTOCOLS, and PATTERNS - nothing else. Looking back, we could see where their is major value in sticking with something that is "tried and true." If we could use web based patterns and protocols for a web based API we could not only get instant adoption but gain the efficiencies and effectiveness of technologies that "just work."
This next generation of API is, ironically based on foundations that have been in place for years. We chose MVC as the application architecture, OAUTH protocol for Authentication, REST and HTTP 1.1 as the transport. This API should give web developers an tool where all they have to think about is what to do with the resources.
Thank you for partnering with us over the years; we have a lot of fun stuff up ahead and we hope to see you at the Dev track @ DC09!