You Can (Not) Request

You would think a software development platform used by 200+ organizations would have proper and comprehensive documentation about their API. Unfortunately, Phabricator begs to differ. And that’s the polar opposite of good.

Phabricator’s API, Conduit, provides simple HTTP endpoints to view, edit, and create Phabricator-related objects like projects, tasks, users, and so on. While these APIs are well documented (sans the almost-deprecated APIs), it seems that they forgot how to document the most important part: how to use those APIs.

2. example
The example that should be working

“But Putra they provide example requests in arc, cURL, and PHP at the bottom of the page. Are you blind?”. No I’m not, atleast not yet. While the example cURL command works for our own Phabricator, it didn’t work for our partner’s:

2. concat_v
The same API call on our Phabricator (top) and our partner’s (bottom). The sensitive information are censored.

It is true that the Phab’s version differs between our own and our partner’s, but the examples provided by Phabricator are exactly the same. This is kind of stupid.


Conduit the right way

Then how should we make API call to Conduit? Well we’re lucky because:

  1. Phabricator has a command-line utility arcanist that can be used to communicate with it, presumable via Conduit API
  2. Our Phabricator is not on secure HTTP (HTTPS), so we can sniff the HTTP request from and to it

So, I fire up the good ol’ Wireshark which can capture network traffics on my local network. It also can display the content of unsecured (non-HTTPS) HTTP request, so we can figure out how arcanist make a Conduit API call:

2. wireshark
Is this what they call a “self-documenting” code?

Bingo! So the structure of the POST parameters of a Conduit API call is as follows:

"__conduit__" = 1
"output" = "json"
"params" = "{ ..., "__conduit__": {"token": } }"

The weird thing is, upon searching “__conduit__” on Google, the only results that shows up are from another Conduit API wrappers. No documentation whatsoever mentioned this keyword. Now we can do proper API calls on our partner’s Phab:

2. peentarphab_succ
Yay!

Well, this whole ordeal was totally unnecessary if Phacility would document their API better. Let’s hope they don’t introduce any updates to arcanist or Phab that will broke this mehod.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s