<template>
  <div>
    <div class="title">
      <h1>REST API reference</h1>   
      <p>Documentation for the Dotty REST API.</p>
    </div>
   
    <p>We recommend that most people use the <router-link :to="{name: 'DocumentationClient'}">official CLI client</router-link>, <span class="code">dotty</span>, to use Dotty.</p>
    <p>However, since this tool is simply a wrapper around the Dotty HTTP API, then some people may prefer to use this directly or to write their own tool using this API.</p>
    <div class="alert alert-info">
      By using the Dotty client or API you agree to Dotty's <a href="/privacy" target="_blank">Privacy Policy</a> and <a href="/terms" target="_blank">Terms of Use</a>.
    </div>

    <h3>API Host</h3>
    <p>All requests to Dotty should be made to the API host over HTTPS, at this URL:</p>
    <div class="code-block">
      https://api.dotty.cloud
    </div>

    <h3>API authentication</h3>
    <p>Some resource/method combinations require authentication in order to protect resources and isolate individual user accounts.</p>
    <p>In the documentation, such resources and methods will be labelled as <span class="label label-info">authentication required</span>. Requests to these resources will need a HTTP header in addition to those specified by the resource/method in question:</p>
    <div class="code-block">
      Authorization: xxx.yyy.zzz
    </div>
    <p>Where <span class="code">xxx.yyy.zzz</span> is the access token returned by registration and login actions described below.</p>

    <h3>API errors</h3>
    <p>Any errors encountered when using the REST API will be described by a suitable response code and, where appropriate, a response body containing text describing the problem in more detail.</p>
    <p>When using the API, clients should respect such status codes and behave accordingly. If the status code is of the format 2xx, then the request was successful and the required action occurred correctly or the required data is included in the response.</p>

    <h3>API resources</h3>
    <p>This section lists the resources available through the REST API.</p>

    <h4><span class="code"> POST /accounts</span></h4>
    <p>This is the only method available for the /accounts resource and the result of a successful request is the creation of a new Dotty account and retrieval of an access token providing access to the Dotty account.</p>
    <h5>Request</h5>
    <p>The body of the request should comprise a JSON object containing the email address and password for the new account, e.g.:</p>
    <pre>
    POST /accounts
    Content-Type: application/json

    {
      "email": "jane@example.com",
      "password": "password"
    }
    </pre>

    <h5>Response</h5>
    <p>Given a 200 status code, the response body will, in plain text, contain an access token which should be stored and used in future authenticated requests (see section about authentication above).</p>

    <h4><span class="code">POST /accounts/password/tokens</span></h4>
    <p>Generates a password-reset email to be sent to the specified email address.</p>
    <h5>Request body</h5>
    <p>The body of the request should simply contain the email address of the account for which the password-reset email is being requested:</p>
    <pre>
      jane@example.com
    </pre>
    <h5>Response</h5>
    <p>Given a 2xx status code, response body and headers will contain no useful information.</p>

    <h4><span class="code">PUT /accounts/password/tokens</span></h4>
    <p>Accepts a password-reset token (received in an email as the result of calling <span class="code">POST /accounts/password/tokens</span>) and a password and changes the relevant account's password to the specified one.</p>
    <h5>Request body</h5>
    <p>The body of the request should comprise a JSON object containing the token and a new password for the account, e.g.:</p>
    <pre>
      {
        "token": "xxx.yyy.zzz",
        "password": "password"
      }
    </pre>
    <h5>Request headers</h5>
    <p>Since the body is JSON, this should be specified:</p>
    <div class="code-block">
      Content-Type: application/json
    </div>
    <h5>Response</h5>
    <p>Given a 2xx status code, response body and headers will contain no useful information.</p>
    <h5>Notes</h5>
    <p>Password-reset tokens are valid for three hours after generation.</p>

    <h4><span class="code">POST /tokens</span></h4>
    <p>Create a new access token for an existing user account and return this to the caller, logging the user in.</p>
    <h5>Request body</h5>
    <p>The body of the request should comprise a JSON object containing the email address and password for the account, e.g.:</p>
    <pre>
    {
      "email": "jane@example.com",
      "password": "password"
    }
    </pre>
    <h5>Request headers</h5>
    <p>Since the body is JSON, this should be specified:</p>
    <div class="code-block">
      Content-Type: application/json
    </div>
    <h5>Response</h5>
    <p>Given a 200 status code, the response body will, in plain text, contain an access token which should be stored and used in future authenticated requests (see section about authentication above).</p>

    <h4><span class="code">DELETE /tokens</span> <span class="label label-info">authentication required</span></h4>
    <p>Invalidates the supplied token, 'logging-out' the token's user.</p>
    <h5>Response</h5>
    <p>Given a 200 status code the response body and headers will not contain any useful information.</p>

    <h4><span class="code">DELETE /tokens/others</span> <span class="label label-info">authentication required</span></h4>
    <p>Invalidates all <em>other</em> tokens associated with the authenticated account, thus 'logging-out' all other authenticated systems.</p>
    <h5>Response</h5>
    <p>Given a 200 status code the response body and headers will not contain any useful information.</p>

    <h4><span class="code">DELETE /tokens/all</span> <span class="label label-info">authentication required</span></h4>
    <p>Invalidates <em>all</em> tokens associated with the authenticated account, thus 'logging-out' all authenticated systems.</p>
    <h5>Response</h5>
    <p>Given a 200 status code the response body and headers will not contain any useful information.</p>

    <h4><span class="code">POST /files</span> <span class="label label-info">authentication required</span></h4>
    <p>Adds and uploads a new file to the Dotty cloud with a specified key name, path, and file payload.</p>
    <p>The specified path will become the file's default path.</p>
    <p>The request will fail if there is already a key with the same name in the account.</p>
    <h5>Request headers</h5>
    <p>Specify the dotfile's key name and path using headers:</p>
    <div class="code-block">
      Key: vimrc<br>
      Default-Path: /home/jane/.vimrc
    </div>
    <h5>Request body</h5>
    <p>The body of your request should plainly contain the file's body.</p>
    <h5>Response</h5>
    <p>Upon a 2xx status code, the response will contain no useful headers or body.</p>

    <h4><span class="code">GET /files</span> <span class="label label-info">authentication required</span></h4>
    <p>Retrieves data about all files stored by the indicated Dotty account.</p>
    <p>Note that responses to requests to this resource do not include the payload of the files themselves. For this, please use the <span class="code">GET /files/:key</span> method instead, as documented in this article.</p>
    <h5>Response body</h5>
    <p>Upon a 2xx status code, the response body will contain a JSON-encoded array of files associated with the account:</p>
    <pre>
    [ 
      {
        "name": "vimrc",
        "defaultPath": "/home/jane/.vimrc"
      },
      ...
    ]
    </pre>
    <p>where <span class="code">name</span> refers to the key of the file.</p>

    
    <h4><span class="code">PUT /files/:key</span> <span class="label label-info">authentication required</span></h4>
    <p>Updates an existing file with a new file payload.</p>
    <h5>Request body</h5>
    <p>The body of your request should plainly contain the file's body.</p>
    <h5>Response</h5>
    <p>Upon a 2xx status code, the response will contain no useful headers or body.</p>

    <h4><span class="code">GET /files/:key</span> <span class="label label-info">authentication required</span></h4>
    <p>Retrieves the latest version of an existing file.</p>
    <h5>Response headers</h5>
    <p>Given a 2xx status code, the response headers will indicate the default path of the file:</p>
    <div class="code-block">
      Default-Path: /home/jane/.vimrc
    </div>
    <h5>Response body</h5>
    <p>Given a 2xx status code, the response body will plainly contain the payload of the requested dotfile.</p>

    <h4><span class="code">DELETE /files/:key</span> <span class="label label-info">authentication required</span></h4>
    <p>Removes the dotfile with the specified key from the user's Dotty account.</p>
    <h5>Response</h5>
    <p>Given a 2xx status code, the response will not contain any useful headers or body.</p>

  </div>
</template>

<script>
export default {
  name: 'documentationRest',
  data() {
    return {
    };
  },
};

</script>

<style scoped lang="scss">

</style>
