<p>Open APIs don't require any type of authentication, these APIs are read-only and only give you publicly accessible data. If you need to modify content and/or want more detailled data (as well as user-private data), you need to use our Connect Authentication system. More information about how to register an app and authenticate it can be found on the <ahref="connect-connect.htm">Connect</a> page.</p>
<p>Every API-Endpoint is prefixed with <codeclass="code">https://spinsha.re/api/</code>. Additionally, every API-call reports back the API-version in form of the <codeclass="code">version</code> property. If you want to ping the API (to check if it's online), you can run the Ping API-call.</p>
<p>Welcome to the SpinShare API Documentation! These pages focus on all the data you can access from SpinSha.re to make cool stuff. Whether you're working on a Twitch bot, a mod for the game or anything else helping, we want you to be able to use our platform to make your projects even better!<br/><br/>So what are we waiting for? Let's create something awesome together!</p>
</div>
<divclass="content">
<h1class="content-title">
Support
</h1>
<p>If you need any help implementing the SpinShare API, feel free to ask us anything in the <codeclass="code">#development</code> channel on our <ahref="https://spinsha.re/discord"target="_blank">Discord Server</a>.</p>
</div>
<divclass="content">
<h1class="content-title">
Changelog
</h1>
<divclass="alert alert-primary"role="alert">
<h4class="alert-heading">Last Update</h4>
This documentation was last updated on 09/09/2020 at 17:48 CEST
</div>
<divclass="card">
<h2class="card-title">09/09/2020</h2>
<ul>
<li>Removed Charts, Reviews and SpinPlays from the UserDetail endpoint</li>
<li>Renamed the UserDetail endpoint to UserOverview</li>
<li>Added an endpoint for UserCharts</li>
<li>Added an endpoint for UserReviews</li>
<li>Added an endpoint for UserSpinPlays</li>
<li>Added song reference to the UserReviews endpoint</li>
<li>Added counts of charts, reviews and spinplays to the UserOverview endpoint</li>
<p>Our Usage Policy serves as the Terms of Service of the SpinShare API. Please follow this ruleset if you are using the SpinShare API.</p>
<divclass="card">
<h2class="card-title">DO</h2>
<ul>
<li>Protect userdata.</li>
<li>Provide users with information about which data you access</li>
<li>Add a label or a backlink to SpinShare</li>
</ul>
</div>
<divclass="card">
<h2class="card-title">DON'T</h2>
<ul>
<li>Use API data for a purpose not connected to SpinShare or Spin Rhythm XD</li>
<li>Obtain passwords or other credentials</li>
<li>Use userdata for marketing or advertisements</li>
<li>Sell or license API data</li>
<li>Scrape API data (caching is excluded from this)</li>
<li>Use this API data to do anything illegal or harmful</li>
</ul>
</div>
<p>We currently don't ratelimit our open APIs. However, we still would like you to keep an eye on your API usage and cache API data whenever possible.</p>
<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>
<divclass="content"id="terminology">
<h1class="content-title">
Terminology
</h1>
<tableclass="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>
<divclass="content"id="creating-a-connection">
<h1class="content-title">
Creating a Connection
</h1>
<divclass="alert alert-secondary"role="alert">
<h4class="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 <ahref="#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 <ahref="#validating-a-token">Validating a Token</a> API endpoint.</p>
</div>
<divclass="content">
<divclass="card"id="getting-a-token">
<h2class="card-title">Getting a Token</h2>
<p>Returns a ConnectToken.</p>
<tableclass="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/>
<tableclass="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>
<divclass="card"id="validating-a-token">
<h2class="card-title">Validating a Token</h2>
<p>Checks if a ConnectToken is still valid.</p>
<tableclass="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/>
<tableclass="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>
<divclass="col-lg-3">
<divclass="content">
<divclass="on-this-page-nav">
<divclass="title">On this page</div>
<ahref="#introduction">Introduction</a>
<ahref="#terminology">Terminology</a>
<ahref="#creating-a-connection">Creating a Connection</a>
<ahref="#getting-a-token">Getting a Token</a>
<ahref="#validating-a-token">Validating a Token</a>
<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>
<divclass="content"id="terminology">
<h1class="content-title">
Terminology
</h1>
<tableclass="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>
<divclass="content"id="creating-a-connection">
<h1class="content-title">
Creating a Connection
</h1>
<divclass="alert alert-secondary"role="alert">
<h4class="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 <ahref="#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 <ahref="#validating-a-token">Validating a Token</a> API endpoint.</p>
{%blocktitle%}Endpoints & Versioning{%endblock%}
{%blockcontent%}
<divclass="row justify-content-center">
<divclass="col-lg-7">
<divclass="content">
<h1class="content-title">
Endpoints & Versioning
</h1>
<p>Every API-Endpoint is prefixed with <codeclass="code">https://spinsha.re/api/</code>. Additionally, every API-call reports back the API-version in form of the <codeclass="code">version</code> property. If you want to ping the API (to check if it's online), you can run the Ping API-call.</p>
<p>Welcome to the SpinShare API Documentation! These pages focus on all the data you can access from SpinSha.re to make cool stuff. Whether you're working on a Twitch bot, a mod for the game or anything else helping, we want you to be able to use our platform to make your projects even better!<br/><br/>So what are we waiting for? Let's create something awesome together!</p>
</div>
<divclass="content">
<h1class="content-title">
Support
</h1>
<p>If you need any help implementing the SpinShare API, feel free to ask us anything in the <codeclass="code">#development</code> channel on our <ahref="https://spinsha.re/discord"target="_blank">Discord Server</a>.</p>
</div>
<divclass="content">
<h1class="content-title">
Changelog
</h1>
<divclass="alert alert-primary"role="alert">
<h4class="alert-heading">Last Update</h4>
This documentation was last updated on 09/09/2020 at 19:50 CEST
</div>
<divclass="card">
<h2class="card-title">09/09/2020</h2>
<ul>
<li>Removed Charts, Reviews and SpinPlays from the UserDetail endpoint</li>
<li>Renamed the UserDetail endpoint to UserOverview</li>
<li>Added an endpoint for UserCharts, UserReviews and UserSpinPlays</li>
<li>Added song reference to the UserReviews endpoint</li>
<li>Added counts of charts, reviews and spinplays to the UserOverview endpoint</li>
<li>Ported the documentation to the main codebase</li>
<li>Added a deprecation warning to the PopularSongs endpoint</li>
<p>Our Usage Policy serves as the Terms of Service of the SpinShare API. Please follow this ruleset if you are using the SpinShare API.</p>
<divclass="card">
<h2class="card-title">DO</h2>
<ul>
<li>Protect userdata.</li>
<li>Provide users with information about which data you access</li>
<li>Add a label or a backlink to SpinShare</li>
</ul>
</div>
<divclass="card">
<h2class="card-title">DON'T</h2>
<ul>
<li>Use API data for a purpose not connected to SpinShare or Spin Rhythm XD</li>
<li>Obtain passwords or other credentials</li>
<li>Use userdata for marketing or advertisements</li>
<li>Sell or license API data</li>
<li>Scrape API data (caching is excluded from this)</li>
<li>Use this API data to do anything illegal or harmful</li>
</ul>
</div>
<p>We currently don't ratelimit our open APIs. However, we still would like you to keep an eye on your API usage and cache API data whenever possible.</p>
