@title Conduit Technical Documentation
@group conduit

Technical overview of the Conduit API.

= Overview =

Conduit is an informal mechanism for transferring ad-hoc JSON blobs around on
the internet.

Theoretically, it provides an API to Phabricator so external scripts (including
scripts written in other languages) can interface with the applications in the
Phabricator suite. It technically does this, sort of, but it is unstable and
incomplete so you should keep your expectations very low if you choose to build
things on top of it.

NOTE: Hopefully, this should improve over time, but making Conduit more robust
isn't currently a major project priority because there isn't much demand for it
outside of internal scripts. If you want to use Conduit to build things on top
of Phabricator, let us know so we can adjust priorities.

Conduit provides an authenticated HTTP API for Phabricator. It is informal and
extremely simple: you post a JSON blob and you get a JSON blob back. You can
access Conduit in PHP with @{class@libphutil:ConduitClient}, or in any language
by executing ##arc call-conduit method## (see ##arc help call-conduit## for
more information). You can see and test available methods at ##/conduit/## in
the web interface.

Arcanist is implemented using Conduit, and @{class:PhabricatorIRCBot} is
intended as a practical example of how to write a program which interfaces with
Phabricator over Conduit.

= Class Relationships =

The primary Conduit workflow is exposed at ##/api/##, which routes to
@{class:PhabricatorConduitAPIController}. This controller builds a
@{class:ConduitAPIRequest} representing authentication information and POST
parameters, instantiates an appropriate subclass of @{class:ConduitAPIMethod},
and passes the request to it. Subclasses of @{class:ConduitAPIMethod} implement
the actual methods which Conduit exposes.

Conduit calls which fail throw @{class:ConduitException}, which the controller
handles.

There is a web interface for viewing and testing Conduit called the "Conduit
Console", implemented by @{class:PhabricatorConduitConsoleController} at
##/conduit/##.

A log of connections and calls is stored by
@{class:PhabricatorConduitConnectionLog} and
@{class:PhabricatorConduitMethodCallLog}, and can be accessed on the web via
@{class:PhabricatorConduitLogController} at ##/conduit/log/##.

Conduit provides a token-based handshake mechanism used by
##arc install-certificate## at ##/conduit/token/##, implemented by
@{class:PhabricatorConduitTokenController} which stores generated tokens using
@{class:PhabricatorConduitCertificateToken}.