Encapsulation is one of the fundamental concept in Object-Oriented Programming (OOP). It hides implementation details of a class, which from outside view are not important at all. Rather than doing everything from scratch, encapsulation provides (relatively) simple endpoints for use by external classes.
To enclose in or as if in a capsule
— IEEE, 1983
Not very useful, isn’t it?
Encapsulation (also information hiding) consists of separating the external aspects of an object which are accessible to other objects, from the internal implementation details of the object, which are hidden from other objects.
–Rumbaugh et al, 1991
Now that’s better.
Put simply, encapsulation hides unnecessary details about technical implementation—the “how” of an algorithm—while exposing only the important part, the purpose of said algorithm.
It’s like exposing a method called invSqrt(x) from a mathematical module. We know that said method calculates 1/sqrt(x), but do we really need to know how that algorithm calculates it? Chances are we don’t, unless you’re interested in some evil floating point bit level hacking.
Meet RbCAW, the Ruby Conduit API Wrapper
Phabricator’s API, Conduit, consists of numerous HTTP URIs which accept both GET and POST request method and in exchange return a JSON document. As communication with Conduit’s endpoints will be done frequently throughout Phrogress’ codebase, it is going to be a hassle to form a HTTP request and then parse the JSON everytime an API call is made.
So, an API wrapper is needed. The wrapper’s job is to encapsulate all interaction with Conduit. It should provide simple, easy to use methods for fetching information from Phabricator.
We decided to develop our own API wrapper (which I call RbCAW
yea I know it sounds stupid but still) because :
- The exsisting wrappers (for Ruby) we found is at least 1 year old, and most of the API endpoints it uses are marked as “frozen”—which means almost deprecated—very recently on January 2017.
- The exsisting wrappers also require authentication method I consider rather convoluted. The API token method I planned for RbCAW is (supposed to be) simpler and easier to mantain.
Structure and Functionality Overview
Basic structure and functionality of RbCAW is inspired by PRAW, the Python Reddit API Wrapper. Yes, I even plagiarized the name.
The basic functionalities that RbCAW should provide (at least the ones I could think of) are:
- Authentication via Phabricator’s OAuth Server. This requires installing experimental Phabricator application—”prototypes”—which needs to be configured from Phabricator’s command line interface. OAuth Server authentication also requires our project to be deployed on the internet with a permanent URL. Because of those, this feature might be delivered at the very last.
- Simple methods to fetch information from Phabricator into native Ruby variables (and not JSON strings). This is the main point of an API wrapper.
- HTTP requests made by RbCAW should be as infrequent as possible to reduce server load. This can be achieved by using “lazy models”, a term I coined from PRAW. This method will be elaborated in another post.
Because every functionality of Phrogress depends on interaction with Phabricator (and hence, Conduit), this wrapper must be developed very early on the project’s lifecycle. On the next post I will elaborate just how fun it is to work with Conduit’s API endpoints.