[Summary view] [Print] [Text view]

   1  @title Conduit Technical Documentation
   2  @group conduit
   3  
   4  Technical overview of the Conduit API.
   5  
   6  = Overview =
   7  
   8  Conduit is an informal mechanism for transferring ad-hoc JSON blobs around on
   9  the internet.
  10  
  11  Theoretically, it provides an API to Phabricator so external scripts (including
  12  scripts written in other languages) can interface with the applications in the
  13  Phabricator suite. It technically does this, sort of, but it is unstable and
  14  incomplete so you should keep your expectations very low if you choose to build
  15  things on top of it.
  16  
  17  NOTE: Hopefully, this should improve over time, but making Conduit more robust
  18  isn't currently a major project priority because there isn't much demand for it
  19  outside of internal scripts. If you want to use Conduit to build things on top
  20  of Phabricator, let us know so we can adjust priorities.
  21  
  22  Conduit provides an authenticated HTTP API for Phabricator. It is informal and
  23  extremely simple: you post a JSON blob and you get a JSON blob back. You can
  24  access Conduit in PHP with @{class@libphutil:ConduitClient}, or in any language
  25  by executing ##arc call-conduit method## (see ##arc help call-conduit## for
  26  more information). You can see and test available methods at ##/conduit/## in
  27  the web interface.
  28  
  29  Arcanist is implemented using Conduit, and @{class:PhabricatorIRCBot} is
  30  intended as a practical example of how to write a program which interfaces with
  31  Phabricator over Conduit.
  32  
  33  = Class Relationships =
  34  
  35  The primary Conduit workflow is exposed at ##/api/##, which routes to
  36  @{class:PhabricatorConduitAPIController}. This controller builds a
  37  @{class:ConduitAPIRequest} representing authentication information and POST
  38  parameters, instantiates an appropriate subclass of @{class:ConduitAPIMethod},
  39  and passes the request to it. Subclasses of @{class:ConduitAPIMethod} implement
  40  the actual methods which Conduit exposes.
  41  
  42  Conduit calls which fail throw @{class:ConduitException}, which the controller
  43  handles.
  44  
  45  There is a web interface for viewing and testing Conduit called the "Conduit
  46  Console", implemented by @{class:PhabricatorConduitConsoleController} at
  47  `/conduit/`.
  48  
  49  A log of connections and calls is stored by
  50  @{class:PhabricatorConduitConnectionLog} and
  51  @{class:PhabricatorConduitMethodCallLog}, and can be accessed on the web via
  52  @{class:PhabricatorConduitLogController} at ##/conduit/log/##.
  53  
  54  Conduit provides a token-based handshake mechanism used by
  55  `arc install-certificate` at `/conduit/token/`, implemented by
  56  @{class:PhabricatorConduitTokenController} which stores generated tokens using
  57  @{class:PhabricatorConduitCertificateToken}.