146 

   147 HTTP Version 2 Transport

   148 ------------------------

   149 

   150 **Experimental - feature under active development**

   151 

   152 Version 2 of the HTTP protocol is exposed under the ``/api/*`` URL space.

   153 It's final API name is not yet formalized.

   154 

   155 Commands are triggered by sending HTTP requests against URLs of the

   156 form ``<permission>/<command>``, where ``<permission>`` is ``ro`` or

   157 ``rw``, meaning read-only and read-write, respectively and ``<command>``

   158 is a named wire protocol command.

   159 

   160 Commands that modify repository state in meaningful ways MUST NOT be

   161 exposed under the ``ro`` URL prefix. All available commands MUST be

   162 available under the ``rw`` URL prefix.

   163 

   164 Server adminstrators MAY implement blanket HTTP authentication keyed

   165 off the URL prefix. For example, a server may require authentication

   166 for all ``rw/*`` URLs and let unauthenticated requests to ``ro/*``

   167 URL proceed. A server MAY issue an HTTP 401, 403, or 407 response

   168 in accordance with RFC 7235. Clients SHOULD recognize the HTTP Basic

   169 (RFC 7617) and Digest (RFC 7616) authentication schemes. Clients SHOULD

   170 make an attempt to recognize unknown schemes using the

   171 ``WWW-Authenticate`` response header on a 401 response, as defined by

   172 RFC 7235.

   173 

   174 Read-only commands are accessible under ``rw/*`` URLs so clients can

   175 signal the intent of the operation very early in the connection

   176 lifecycle. For example, a ``push`` operation - which consists of

   177 various read-only commands mixed with at least one read-write command -

   178 can perform all commands against ``rw/*`` URLs so that any server-side

   179 authentication requirements are discovered upon attempting the first

   180 command - not potentially several commands into the exchange. This

   181 allows clients to fail faster or prompt for credentials as soon as the

   182 exchange takes place. This provides a better end-user experience.

   183 

   184 Requests to unknown commands or URLS result in an HTTP 404.

   185 TODO formally define response type, how error is communicated, etc.