Behind the Scenes: Apperian’s Open APIs

My name is Nicole Perrault, and I am the Head of Documentation here at Apperian. It is my job to take lots of technical information and distill it down to a manageable collection of content that helps our customers use the Apperian platform. A large part of my job is interviewing the engineers at Apperian to research a technical topic or understand the ins and outs of a new feature. I recently sat down with Frank Chiang, one of Apperian’s stellar software engineers, to learn more about Apperian’s web services architecture. Frank is the type of guy who uses the words “code” and “beautiful” in the same sentence. A lot. He is passionate about what he does, and it shows in his work.

Apperian released a collection of open APIs. Just like that sounds, we are breaking the doors down to expose a set of programming interfaces to our web services so customers and partners can harness the power of the Apperian platform as part of a custom enterprise mobility solution. It’s exciting stuff, and I had a lot of questions. Why, for example, did we go with a REST API? Why did we choose Python instead of the other gazillian programming languages? What the heck is Flask, and why should I care?

Here are some excerpts from my interview with Frank. In the boxes, I define some terms for readers less familiar with web services technology. Just skip those bits if you don’t need them.

Web services provide a way for programs to communicate over 
the Internet. Through an application programming interface (API), 
one program can make a request to another program's web 
service and then use the response from that web service 
to perform functions in its web site or application. Let's
consider a basic example of this with Apperian's API. Say 
that an Apperian customer wants to add a button to its 
corporate web site that lets its employees easily sign up for the 
enterprise App Catalog. The code behind that button will send 
a request to Apperian’s web services to add a new user 
to EASE. Apperian will respond with a link to download 
the App Catalog to the user’s mobile device. 

REST (Representational State Transfer) defines a set of 
architectural principles for designing web services. REST focuses 
on a system's resources (or functions), exposing each resource 
via a URL. A program can access that URL to receive data 
about the resource, similar to how you type a URL in your
browser and get a web page back.

NP:  We had been using a JSON-RPC API. Why did we switch to a REST API?

FC:  REST has gained widespread acceptance as a simpler alternative to JSON-RPC, SOAP, and other protocols. One of our goals when designing the API was that it should be intuitive. People should be able to guess what each interface should do before reading pages of detailed documentation. [NP: Wait. Was this a dig on documentation?] This is where REST really shines and ultimately what caused us to switch from the existing JSON-RPC protocol.

REST is sometimes a tricky subject because REST purists can be quite fanatical on its implementation. We were determined to be as RESTful as possible but to deviate if the alternative was more intuitive. So it would be more accurate to describe the EASE API as RESTful rather than pure REST, and we prefer it that way.

Python, PHP, Java, and C# are examples from a long list of 
object-oriented programming languages. Python and PHP are 
both interpreted languages, meaning they execute 
instructions directly. Compiled languages, like Java and C#, need 
to first compile the program into machine-language instructions. 
There are many similarities and differences —pros and cons— 
among the array of object-oriented languages. The language 
wars continue, but Python is universally well known for its 
intuitive syntax and readability.

[NP] When we switched to REST, we started programming in Python instead of PHP. Why Python?

[FC] We knew that we didn’t want to continue to use PHP since its philosophy of “try as hard as possible not to error out” didn’t lend itself well to an enterprise API, where we wanted everything to behave as consistently as possible. We mulled over C#, being a more refined version of Java, but couldn’t bring ourselves to switch our LAMP stack to the Microsoft stack.

A stack is a software bundle that, when used together, forms a 
solution stack of technologies to support application 
servers. LAMP is short for Linux, Apache, MySQL and PHP, 
and refers to an open-source stack that uses Linux as the 
operating system, Apache as the Web server, MySQL as the 
relational database management server, and PHP as the 
object-oriented language. Python is often used instead of PHP.
At Apperian, we also use PostgreSQL instead of MySQL. The
Microsoft stack, or WISA, uses Windows (operating system), 
Internet Information Services (file/web server), SQL Server 
(database software), and ASP.NET, although the exact 
combination of software may vary. For example, ASP.NET may 
be replaced or supplemented by other .NET technologies.

Python was a language that we all loved. It was beautiful, the community was very vibrant, and the code was easy to read and maintain. [NP: “Code” and “beautiful” in the same sentence. See. What did I tell you?]  Ruby was very similar but we leaned towards Python since there were already existing scripts in our codebase that were written in Python.

One of Python’s biggest shortcomings is its performance when compared to compiled languages. This brought languages such as Scala into the discussion since its performance is almost on-par with C and has a fantastic actor model, which lends itself well to an API. In the end, we decided that heavy uses of Python in Dropbox and Quora was proof that Python was fast enough for high-load environments. We also liked the web frameworks available to us with Python, and we ultimately decided to go with Flask.

A web framework is a collection of packages or modules that act 
as a layer on top of the HTTP layer. A web framework 
allows developers to more easily write web services by 
handling lower-level details, like catching errors and 
interface routing. Django is the largest Python-based 
web framework. Flask is a smaller, yet still powerful framework, 
known for being easy to use.

[NP] Why Flask?

[FC]  There are lots of web frameworks for Python. Using a heavyweight web framework like Django was never an option for us. We wanted a thin layer that would stay out of our way but also scale upwards to be able to support heavy loads. This led us to consider micro-frameworks such as webapp2 and Flask.The framework webapp2 comes from a derivation of webapp, which was created by the Google App Engine team. So webapp2 certainly had the right pedigree. Flask was the brainchild of Armin Ronacher, who basically started Flask (then called Denied) as an April Fool’s joke by slapping together werkzeug for routing, simplejson for serialization, and jinja2 for templating, and calling it a “micro-framework” as a dig to other micro-frameworks. To his surprise, this caught like wildfire and prompted him to actually create Flask as we know it today. The web framework decision was probably the one that we were most passionate about, which is funny in hindsight since our main criteria was that it should be as thin as possible. We spent weekends playing with each framework and putting it through strenuous load tests.  In the end, we decided on Flask for its active community, clear documentation [NP: Yaa!] , and elegant code structure, although my belief is that we wouldn’t have been wrong either way. As of yet, we haven’t regretted our decision at all.

[NP] I just had a vision of all you engineers huddled in a conference room passionately debating web frameworks. Tell me the truth. How contentious do those discussions get? Have you ever wanted to just throw down your whiteboard marker and clock someone?

[FC] Just the normal name calling and hair pulling that are the trademarks of all healthy red-blooded engineers. We’re passionate about our work but we also respect each other. While we did challenge each other during the conversations, we all understood that everyone’s ultimate goal was to build a product that would stand the test of time. Underlying all discussions were the 3 Rs: Reusable, Resilient, Responsive. When we started architecting our API, our philosophy was to build the foundation on these three main pillars. Our vision was to make the API the core of the entire EASE product. Our app catalogs and administrative portal would both be consumers of the API, and there would be no special treatment for internal Apperian consumers over third-party consumers (that is, our customers and partners). In this way, we would “eat our own dogfood,” identify any pain points that our API consumers could face, and quickly fix them. Actually, I could go on and on about the 3 Rs.

Nicole Perrault is the Head of Documentation at Apperian and can be reached at nperrault@apperian.com.