{% extends 'apidocs/base.html.twig' %}

{% block title %}Connect{% endblock %}

{% block content %}
    <div class="row justify-content-center">
        <div class="col-lg-7">
            <div class="content" id="introduction">
                <h1 class="content-title">
                    Introduction
                </h1>
                
                <p>This document outlines how to connect a SpinShare userprofile with your application and how you can use this connection to perform user actions such as creating reviews or adding charts to playlists.</p>
            </div>
            <div class="content" id="terminology">
                <h1 class="content-title">
                    Terminology
                </h1>

                <table class="table table-bordered">
                    <tr>
                        <th>User</th>
                        <td>A "User" is a SpinShare userprofile.</td>
                    </tr>
                    <tr>
                        <th>ConnectApp</th>
                        <td>A "ConnectApp" is your application, bot or whatever.</td>
                    </tr>
                    <tr>
                        <th>Connection</th>
                        <td>A "Connection" is a relationship between a ConnectApp and a User. A User can always revoke access to a ConnectApp by going into the usersettings on SpinShare.</td>
                    </tr>
                    <tr>
                        <th>ConnectCode</th>
                        <td>A "ConnectCode" is a 6 character code that is used for establishing the connection between a User and a ConnectApp. This code will change every 15 seconds as long as the user is on the SpinShare connect page.</td>
                    </tr>
                    <tr>
                        <th>ConnectToken</th>
                        <td>A "ConnectToken" is a series of characters used along with your ApiKey to verify you are allowed to perform certain actions and ping certain api endpoints. This token is valid until the user revokes access.</td>
                    </tr>
                </table>
            </div>

            <div class="content" id="creating-a-connection">
                <h1 class="content-title">
                    Creating a Connection
                </h1>

                <div class="alert alert-secondary" role="alert">
                    <h4 class="alert-heading">Attention</h4>
                    API access is handled privately as of now. Please refer to the developers on the SpinShare Discord to receive API access.
                </div>

                <p>The SpinShare API does not consume login credentials for protected API endpoints but rather a simple apikey/token solution. Users have to connect to a ConnectApp once by inputting a 6 character long ConnectCode that changes every 15 seconds.</p>
                <strong>Steps to establish a Connection</strong>
                <p>Prompt the user to input their connect code. The code can be found on within the profile settings under the "Connect" tab.</p>
                <p>Put the ConnectCode through the <a href="#getting-a-token">Getting a Token</a> API endpoint along with your ApiKey to generate a ConnectToken.</p>
                <p>Save the ConnectToken locally and use it for protected API endpoints. If you need to verify if your ConnectToken is still valid, you can use the <a href="#validating-a-token">Validating a Token</a> API endpoint.</p>
            </div>

            <div class="content">
                <div class="card" id="getting-a-token">
                    <h2 class="card-title">Getting a Token</h2>
                    <p>Returns a ConnectToken.</p>

                    <table class="table table-bordered">
                        <tr>
                            <th>Method</th>
                            <td>GET</td>
                        </tr>
                        <tr>
                            <th>Endpoint</th>
                            <td>/connect/getToken</td>
                        </tr>
                        <tr>
                            <th>Query Parameters</th>
                            <td>(string) connectCode<br />
                                (string) connectAppApiKey</td>
                        </tr>
                    </table>

                    <br />
                    
                    <br />

                    <strong>Responses</strong>
                    <br /><br />
                    <table class="table table-bordered">
                        <thead>
                            <tr>
                                <th>Code</th>
                                <th>Explaination</th>
                            </tr>
                        </thead>
                        <tbody>
                            <tr>
                                <td>200</td>
                                <td>OK. The body contains the ConnectToken</td>
                            </tr>
                            <tr>
                                <td>400</td>
                                <td>Parameters are missing. The body contains the needed parameters and their value</td>
                            </tr>
                            <tr>
                                <td>403</td>
                                <td>The ConnectCode or ApiKey was wrong.</td>
                            </tr>
                        </tbody>
                    </table>
                </div>
                
                <div class="card" id="validating-a-token">
                    <h2 class="card-title">Validating a Token</h2>
                    <p>Checks if a ConnectToken is still valid.</p>

                    <table class="table table-bordered">
                        <tr>
                            <th>Method</th>
                            <td>GET</td>
                        </tr>
                        <tr>
                            <th>Endpoint</th>
                            <td>/connect/validateToken</td>
                        </tr>
                        <tr>
                            <th>Query Parameters</th>
                            <td>(string) connectToken</td>
                        </tr>
                    </table>

                    <br /><br />

                    <strong>Responses</strong>
                    <br /><br />
                    <table class="table table-bordered">
                        <thead>
                            <tr>
                                <th>Code</th>
                                <th>Explaination</th>
                            </tr>
                        </thead>
                        <tbody>
                            <tr>
                                <td>200</td>
                                <td>The ConnectToken is valid.</td>
                            </tr>
                            <tr>
                                <td>403</td>
                                <td>The ConnectToken is not valid.</td>
                            </tr>
                        </tbody>
                    </table>
                </div>
            </div>
        </div>
        <div class="col-lg-3">
            <div class="content">
                <div class="on-this-page-nav">
                    <div class="title">On this page</div>
                    <a href="#introduction">Introduction</a>
                    <a href="#terminology">Terminology</a>
                    <a href="#creating-a-connection">Creating a Connection</a>
                    <a href="#getting-a-token">Getting a Token</a>
                    <a href="#validating-a-token">Validating a Token</a>
                </div>
            </div>
        </div>
    </div>
{% endblock %}