Initial Release
This commit is contained in:
@@ -0,0 +1,57 @@
|
||||
<article
|
||||
id="applications"
|
||||
authorId=""
|
||||
categoryId="api"
|
||||
title="Applications"
|
||||
created="500"
|
||||
snippet="Developer documentation for Applications"
|
||||
banner=""
|
||||
noindex="false"
|
||||
>
|
||||
<header>Introduction</header>
|
||||
<text>
|
||||
Applications allow you to integrate the suzzy API into your projects.
|
||||
You can create and manage them while in the <a href='/profile/applications'>Applications</a>
|
||||
section of your profile.
|
||||
</text>
|
||||
|
||||
<subheader>Application Object</subheader>
|
||||
<table>
|
||||
<row>
|
||||
<column>Field</column>
|
||||
<column>Type</column>
|
||||
<column>Description</column>
|
||||
</row>
|
||||
<row>
|
||||
<column>id</column>
|
||||
<column>integer</column>
|
||||
<column>Unique Application ID</column>
|
||||
</row>
|
||||
<row>
|
||||
<column>created</column>
|
||||
<column>Date</column>
|
||||
<column>ISO Timestamp of when application was created</column>
|
||||
</row>
|
||||
<row>
|
||||
<column>flags</column>
|
||||
<column>integer</column>
|
||||
<column>the application's public flags</column>
|
||||
</row>
|
||||
<row>
|
||||
<column>name</column>
|
||||
<column>string</column>
|
||||
<column>the application's name</column>
|
||||
</row>
|
||||
<row>
|
||||
<column>description</column>
|
||||
<column>string?</column>
|
||||
<column>the application's description</column>
|
||||
</row>
|
||||
<row>
|
||||
<column>icon</column>
|
||||
<column>string?</column>
|
||||
<column>the application's image hash</column>
|
||||
</row>
|
||||
</table>
|
||||
|
||||
</article>
|
||||
@@ -0,0 +1,23 @@
|
||||
<article
|
||||
id="changelog"
|
||||
authorId=""
|
||||
categoryId="api"
|
||||
title="Changelog"
|
||||
created="-1"
|
||||
snippet="Changelog for suzzy APIs and Services"
|
||||
banner=""
|
||||
noindex="false"
|
||||
>
|
||||
<header>Notices</header>
|
||||
<text>Important and Breaking changes will be listed below:</text>
|
||||
<list>
|
||||
<item>Nothing to report!</item>
|
||||
</list>
|
||||
<header>History</header>
|
||||
<subheader>Initial Release</subheader>
|
||||
<quote>Date: May 12th 2024</quote>
|
||||
<list>
|
||||
<item>Applications are now generally available</item>
|
||||
<item>suzzy Library now available</item>
|
||||
</list>
|
||||
</article>
|
||||
@@ -0,0 +1,155 @@
|
||||
<article
|
||||
id="oauth2"
|
||||
authorId=""
|
||||
categoryId="api"
|
||||
title="OAuth2"
|
||||
created="400"
|
||||
snippet="Developer documentation for OAuth2"
|
||||
banner=""
|
||||
noindex="false"
|
||||
>
|
||||
<header>Resources</header>
|
||||
<text>
|
||||
suzzy games provides support for OAuth2 allowing applications to
|
||||
use the API for authorization and retrieval of user data.
|
||||
</text>
|
||||
<text>
|
||||
It is recommended you
|
||||
<a href="/library/api/tutorials#creating-an-application">Create an Application</a>
|
||||
and store the given
|
||||
<c>CLIENT_ID</c> and
|
||||
<c>CLIENT_SECRET</c> for later use.
|
||||
</text>
|
||||
<subheader>OAuth2 URLs</subheader>
|
||||
<table>
|
||||
<row>
|
||||
<column>URL</column>
|
||||
<column>Description</column>
|
||||
</row>
|
||||
<row>
|
||||
<column>https://suzzygames.com/oauth2</column>
|
||||
<column>Base Authorization URL</column>
|
||||
</row>
|
||||
<row>
|
||||
<column>https://apis.suzzygames.com/v1/oauth2/token</column>
|
||||
<column>Token URL</column>
|
||||
</row>
|
||||
<row>
|
||||
<column>https://apis.suzzygames.com/v1/oauth2/token/revoke</column>
|
||||
<column>Token Revocation URL</column>
|
||||
</row>
|
||||
</table>
|
||||
<quote>These endpoints will only accept the content type "application/x-www-form-urlencoded"</quote>
|
||||
<subheader>OAuth2 Scopes</subheader>
|
||||
<text>
|
||||
A list of available scopes, some endpoints will return fields with a
|
||||
<c>null</c> value or return an error if a required scope is unavailable.
|
||||
</text>
|
||||
<table>
|
||||
<row>
|
||||
<column>Name</column>
|
||||
<column>Description</column>
|
||||
</row>
|
||||
<row>
|
||||
<column>identify</column>
|
||||
<column>Allows access to /users/@me endpoint</column>
|
||||
</row>
|
||||
<row>
|
||||
<column>email</column>
|
||||
<column>Allows /users/@me endpoint to return the user's email</column>
|
||||
</row>
|
||||
<row>
|
||||
<column>connections</column>
|
||||
<column>Allows access to /users/@me/applications endpoint</column>
|
||||
</row>
|
||||
</table>
|
||||
|
||||
<!-- OAuth2 User Flow -->
|
||||
<header>Authorization Code Grant</header>
|
||||
<text>
|
||||
This is most commonly known as <b>standard OAuth2</b>, where the user
|
||||
follows an Authorization Flow in return for an access code which the
|
||||
application can exchange for the user's access token.
|
||||
</text>
|
||||
<quote>
|
||||
All endpoints expect HTTP Basic Auth using your applications
|
||||
CLIENT_ID as the username and CLIENT_SECRET as the password
|
||||
</quote>
|
||||
|
||||
<subheader>Example Authorization URL</subheader>
|
||||
<code syntax="skip">
|
||||
https://suzzygames.com/oauth2?response_type=code&redirect_uri=https%3A%2F%2Fexample.org&client_id=1273&redirect_uri=https%3A%2F%2Fexample.org&scope=identify%20email&state=1734831153572
|
||||
</code>
|
||||
<text>- <c>response_type</c> must always be code, as it is currently the only supported type.</text>
|
||||
<text>- <c>redirect_uri</c> is one of the Redirect URIs set in your application settings, url encoded.</text>
|
||||
<text>- <c>client_id</c> is your Application ID. </text>
|
||||
<text>- <c>scope</c> is a list of <a href="#oauth2-scopes">OAuth2 Scopes</a> delimited by url encoded spaces <c>(%20)</c>.</text>
|
||||
<text>- <c>state</c> is a unique string that will be returned if set.</text>
|
||||
|
||||
<subheader>Example Redirect URL</subheader>
|
||||
<code syntax="skip">
|
||||
https://example.org?code=9AED9A46641F3E3F489523C643C177BB.oboQpOkOSQJvdYYa4WuPq8J3TaYqNgylfq97sa99DRk&state=1734831153572
|
||||
</code>
|
||||
<text>
|
||||
The <c>code</c> can now be exchanged for a user's access token by
|
||||
making a POST request to the <a href="#oauth2-urls">Token URL</a>
|
||||
with the following parameters:
|
||||
</text>
|
||||
<text>- <c>code</c> - parameter taken from the query string</text>
|
||||
<text>- <c>grant_type</c> - value must be <c>authorization_code</c></text>
|
||||
<text>- <c>redirect_uri</c> - the <c>redirect_uri</c> from the authorization url</text>
|
||||
<text>In response you will be bestowed an <a href="#access-token-response">Access Token Response</a></text>
|
||||
|
||||
<subheader>Access Token Response</subheader>
|
||||
<table>
|
||||
<row>
|
||||
<column>Name</column>
|
||||
<column>Type</column>
|
||||
<column>Description</column>
|
||||
</row>
|
||||
<row>
|
||||
<column>access_token</column>
|
||||
<column>string</column>
|
||||
<column>Token to include in authorization header</column>
|
||||
</row>
|
||||
<row>
|
||||
<column>token_type</column>
|
||||
<column>string</column>
|
||||
<column>String to prepend to token in authorization header</column>
|
||||
</row>
|
||||
<row>
|
||||
<column>expires_in</column>
|
||||
<column>number</column>
|
||||
<column>Seconds until access token expires</column>
|
||||
</row>
|
||||
<row>
|
||||
<column>refresh_token</column>
|
||||
<column>string</column>
|
||||
<column>Token to submit when making a refresh request</column>
|
||||
</row>
|
||||
<row>
|
||||
<column>scope</column>
|
||||
<column>string</column>
|
||||
<column>The relevant OAuth2 Scopes for this token (delimited with a space)</column>
|
||||
</row>
|
||||
</table>
|
||||
|
||||
<subheader>Refreshing Access Token</subheader>
|
||||
<text>
|
||||
Once an access token has expired you may refresh it by making a
|
||||
POST request to the <a href="#oauth2-urls">Token URL</a> with
|
||||
the following parameters:
|
||||
</text>
|
||||
<text>- <c>grant_type</c> - value must be <c>refresh_token</c></text>
|
||||
<text>- <c>refresh_token</c> - the user's refresh token</text>
|
||||
<text>In response you will be bestowed a fresh <a href="#access-token-response">Access Token Response</a></text>
|
||||
|
||||
<subheader>Revoking Access Token</subheader>
|
||||
<text>
|
||||
You can revoke an access token by making a POST request to the
|
||||
<a href="#oauth2-urls">Token Revocation URL</a> with the following
|
||||
parameters:
|
||||
</text>
|
||||
<text>- <c>token</c> - the user's access token or refresh token</text>
|
||||
|
||||
</article>
|
||||
@@ -0,0 +1,108 @@
|
||||
<article
|
||||
id="reference"
|
||||
authorId=""
|
||||
categoryId="api"
|
||||
title="Reference"
|
||||
created="100"
|
||||
snippet="References for suzzy APIs and Services"
|
||||
banner=""
|
||||
noindex="false"
|
||||
>
|
||||
<!-- Server URLs -->
|
||||
<header>Sending Requests</header>
|
||||
<text>
|
||||
All requests to the api should be made to the following URL: <c>https://apis.suzzygames.com/v1/</c>
|
||||
</text>
|
||||
|
||||
<!-- Server Ratelimiting -->
|
||||
<header>Ratelimiting</header>
|
||||
<text>
|
||||
Each response will include headers related to ratelimiting, follow them otherwise
|
||||
the server will automatically reject your request and respond with a
|
||||
<c>429 Too Many Requests</c> error.
|
||||
</text>
|
||||
<table>
|
||||
<row>
|
||||
<column>Header</column>
|
||||
<column>Description</column>
|
||||
</row>
|
||||
<row>
|
||||
<column>RateLimit-Limit</column>
|
||||
<column>Request Quota</column>
|
||||
</row>
|
||||
<row>
|
||||
<column>RateLimit-Remaining</column>
|
||||
<column>Requests Remaining</column>
|
||||
</row>
|
||||
<row>
|
||||
<column>RateLimit-Reset</column>
|
||||
<column>Float seconds until Quota Resets</column>
|
||||
</row>
|
||||
</table>
|
||||
<quote>
|
||||
Sending too many bad requests too quickly will result in your IP Address
|
||||
being blocked temporarily.
|
||||
</quote>
|
||||
<quote>
|
||||
Frequent abusers will get the ban hammer!
|
||||
</quote>
|
||||
|
||||
<!-- User Assets -->
|
||||
<header>Content URLs</header>
|
||||
<text>
|
||||
User Uploads <h>(Avatars, Banners, etc.)</h> are available at
|
||||
<c>https://content.suzzygames.com/</c> using the following paths:
|
||||
</text>
|
||||
<table>
|
||||
<row>
|
||||
<column>Name</column>
|
||||
<column>Path</column>
|
||||
</row>
|
||||
<row>
|
||||
<column>User Avatars</column>
|
||||
<column>/avatars/{user.id}/{user.avatar}/{extension}/{size}</column>
|
||||
</row>
|
||||
<row>
|
||||
<column>User Banners</column>
|
||||
<column>/banners/{user.id}/{user.banner}/{extension}/{size}</column>
|
||||
</row>
|
||||
</table>
|
||||
<quote>Image Sizes: Large (192px), Medium (96px), Small (48px)</quote>
|
||||
<quote>Image Extensions: webp, png, gif (if animated)</quote>
|
||||
<quote>Animated images will have their hash begin with "a_"</quote>
|
||||
|
||||
<!-- User Default Assets -->
|
||||
<header>Default Assets</header>
|
||||
<text>
|
||||
Ocasionally users won't have uploaded an avatar, you can use the provided
|
||||
default ones by calculating the index with <c>index = {user.id} % 6</c> and using the follow URL:
|
||||
</text>
|
||||
<text>
|
||||
<c>https://suzzygames.com/assets/images/default-user{index}.png</c>
|
||||
</text>
|
||||
<quote>Signed out users use "default-anon.png" instead</quote>
|
||||
|
||||
<subheader>Default Colors</subheader>
|
||||
<text>
|
||||
Default colors for user profiles are available below:
|
||||
</text>
|
||||
<table>
|
||||
<row>
|
||||
<column>Name</column>
|
||||
<column>Color (Hex)</column>
|
||||
</row>
|
||||
<row>
|
||||
<column>Profile Banner</column>
|
||||
<column>#1D1E2E</column>
|
||||
</row>
|
||||
<row>
|
||||
<column>Profile Background</column>
|
||||
<column>#333550</column>
|
||||
</row>
|
||||
<row>
|
||||
<column>Profile Border</column>
|
||||
<column>#282A3F</column>
|
||||
</row>
|
||||
</table>
|
||||
|
||||
</article>
|
||||
@@ -0,0 +1,28 @@
|
||||
<article
|
||||
id="tutorials"
|
||||
authorId=""
|
||||
categoryId="api"
|
||||
title="Tutorials"
|
||||
created="200"
|
||||
snippet="Simple tutorials on certain things."
|
||||
banner=""
|
||||
noindex="false"
|
||||
>
|
||||
<header>Creating an Application</header>
|
||||
<text>
|
||||
You can create an application using the <a href="https://suzzygames.com/account/applications">My Applications</a>
|
||||
page in the account management portal. Ensure your application has a
|
||||
memorable name and that you keep its secret key secure and private.
|
||||
</text>
|
||||
<image
|
||||
alt="Click on the Create Application Button"
|
||||
caption="Click on the Create Application Button"
|
||||
resource="file://library/tutorials/applications-step-1.png"
|
||||
/>
|
||||
<image
|
||||
alt="You can then edit your Application by clicking on the Edit Button"
|
||||
caption="You can then edit your Application by clicking on the Edit Button"
|
||||
resource="file://library/tutorials/applications-step-2.png"
|
||||
/>
|
||||
<!-- TODO: IMPROVE OAUTH2 TUTORIAL -->
|
||||
</article>
|
||||
@@ -0,0 +1,212 @@
|
||||
<article
|
||||
id="users"
|
||||
authorId=""
|
||||
categoryId="api"
|
||||
title="Users"
|
||||
created="300"
|
||||
snippet="Developer documentation for Users"
|
||||
banner=""
|
||||
noindex="false"
|
||||
>
|
||||
<!-- User Object Reference -->
|
||||
<header>User Object</header>
|
||||
<text>
|
||||
Fields for a user object and the required oAuth2 Scope to view them.
|
||||
Optional fields <h>(Type ending with ?)</h> or hidden fields <h>(Missing oAuth2 Scope)</h>
|
||||
will have their value set as <c>null</c> instead.
|
||||
</text>
|
||||
<table>
|
||||
<row>
|
||||
<column>Field</column>
|
||||
<column>Type</column>
|
||||
<column>Description</column>
|
||||
<column>Required oAuth2 Scope</column>
|
||||
</row>
|
||||
<row>
|
||||
<column>id</column>
|
||||
<column>integer</column>
|
||||
<column>their unique account id</column>
|
||||
<column>identify</column>
|
||||
</row>
|
||||
<row>
|
||||
<column>created</column>
|
||||
<column>timestamp</column>
|
||||
<column>their account creation timestamp</column>
|
||||
<column>identify</column>
|
||||
</row>
|
||||
<row>
|
||||
<column>public_flags</column>
|
||||
<column>integer</column>
|
||||
<column>their public flags (badges)</column>
|
||||
<column>identify</column>
|
||||
</row>
|
||||
<row>
|
||||
<column>username</column>
|
||||
<column>string</column>
|
||||
<column>their username</column>
|
||||
<column>identify</column>
|
||||
</row>
|
||||
<row>
|
||||
<column>displayname</column>
|
||||
<column>string</column>
|
||||
<column>their displayname</column>
|
||||
<column>identify</column>
|
||||
</row>
|
||||
<row>
|
||||
<column>subtitle</column>
|
||||
<column>string</column>
|
||||
<column>their pronouns, status, etc.</column>
|
||||
<column>identify</column>
|
||||
</row>
|
||||
<row>
|
||||
<column>biography</column>
|
||||
<column>string</column>
|
||||
<column>their biography</column>
|
||||
<column>identify</column>
|
||||
</row>
|
||||
<row>
|
||||
<column>accent_background</column>
|
||||
<column>integer</column>
|
||||
<column>their profile background color</column>
|
||||
<column>identify</column>
|
||||
</row>
|
||||
<row>
|
||||
<column>accent_banner</column>
|
||||
<column>integer</column>
|
||||
<column>their profile banner color</column>
|
||||
<column>identify</column>
|
||||
</row>
|
||||
<row>
|
||||
<column>accent_border</column>
|
||||
<column>integer</column>
|
||||
<column>their profile border color</column>
|
||||
<column>identify</column>
|
||||
</row>
|
||||
<row>
|
||||
<column>avatar</column>
|
||||
<column>string?</column>
|
||||
<column>their avatar image hash</column>
|
||||
<column>identify</column>
|
||||
</row>
|
||||
<row>
|
||||
<column>banner</column>
|
||||
<column>string?</column>
|
||||
<column>their banner image hash</column>
|
||||
<column>identify</column>
|
||||
</row>
|
||||
<row>
|
||||
<column>verified</column>
|
||||
<column>boolean</column>
|
||||
<column>has email been verified?</column>
|
||||
<column>identify</column>
|
||||
</row>
|
||||
<row>
|
||||
<column>email</column>
|
||||
<column>string?</column>
|
||||
<column>their email address</column>
|
||||
<column>email</column>
|
||||
</row>
|
||||
</table>
|
||||
<quote>Usernames will always be alphanumeric with underscores and between 3-32 characters long</quote>
|
||||
<quote>Usernames may change without warning, use account IDs instead!</quote>
|
||||
<quote>Displaynames and Subtitles are up to 32 characters long</quote>
|
||||
<quote>Biographies are up to 320 chracters long</quote>
|
||||
<quote>Colors are in Decimal Representation</quote>
|
||||
|
||||
<!-- User Public Flags/Badges -->
|
||||
<header>Public Flags</header>
|
||||
<text>
|
||||
Use a <b>Bitwise AND</b> operation in your language of choice to see if a flag is
|
||||
set for a user. Flags are primarily used for badges which are special achievements
|
||||
that were obtainable for a limited time or gifted to specific users.
|
||||
</text>
|
||||
<table>
|
||||
<row>
|
||||
<column>Value</column>
|
||||
<column>Name</column>
|
||||
<column>Description</column>
|
||||
<column>Obtainable?</column>
|
||||
</row>
|
||||
<row>
|
||||
<column>1 (1 << 0)</column>
|
||||
<column>BADGE_CROWN</column>
|
||||
<column>Reserved for bakonpancakz</column>
|
||||
<column>Never</column>
|
||||
</row>
|
||||
<row>
|
||||
<column>2 (1 << 1)</column>
|
||||
<column>BADGE_VIP</column>
|
||||
<column>Reserved for important users</column>
|
||||
<column>No</column>
|
||||
</row>
|
||||
<row>
|
||||
<column>4 (1 << 2)</column>
|
||||
<column>BADGE_PICROSS</column>
|
||||
<column>Awarded by completing Challenge #1</column>
|
||||
<column>Yes</column>
|
||||
</row>
|
||||
<row>
|
||||
<column>8 (1 << 3)</column>
|
||||
<column>PUBLIC_UNAVAILABLE</column>
|
||||
<column>Account is Unavailable</column>
|
||||
<column>TOS Violation</column>
|
||||
</row>
|
||||
</table>
|
||||
<quote>
|
||||
Unavailable accounts, may be banned or deleted.
|
||||
The reasoning will be sent to the account owners email.
|
||||
</quote>
|
||||
|
||||
<!-- GET /users/@me -->
|
||||
<header>Get Current User</header>
|
||||
<text><c>GET /users/@me</c></text>
|
||||
<text>
|
||||
Returns the current user if you have the <c>identify</c> scope, also
|
||||
returns email if you also have the <c>email</c> scope.
|
||||
</text>
|
||||
|
||||
<!-- GET /users/@me/connections -->
|
||||
<header>Get Connections for Current User</header>
|
||||
<text><c>GET /users/@me/connections</c></text>
|
||||
<text>
|
||||
Requires the <c>connections</c> <a href='/library/api/oauth2#oauth2-scopes'>OAuth2 Scope</a>.
|
||||
Returns an array of <a href="#connection-object">Connection</a> Objects the user is actively connected to.
|
||||
</text>
|
||||
<subheader>Connection Object</subheader>
|
||||
<table>
|
||||
<row>
|
||||
<column>Field</column>
|
||||
<column>Type</column>
|
||||
<column>Description</column>
|
||||
</row>
|
||||
<row>
|
||||
<column>id</column>
|
||||
<column>integer</column>
|
||||
<column>Unique Connection ID</column>
|
||||
</row>
|
||||
<row>
|
||||
<column>created</column>
|
||||
<column>Date</column>
|
||||
<column>ISO Timestamp of when connection was created</column>
|
||||
</row>
|
||||
<row>
|
||||
<column>scopes</column>
|
||||
<column>integer</column>
|
||||
<column>Associated OAuth2 scopes with connection</column>
|
||||
</row>
|
||||
<row>
|
||||
<column>application</column>
|
||||
<column>Application Object</column>
|
||||
<column>An Application Object</column>
|
||||
</row>
|
||||
</table>
|
||||
<text><i>Quick link to</i> <a href="/library/api/applications#application-object">Application Object</a>.</text>
|
||||
|
||||
<!-- GET /users/<user.username> -->
|
||||
<header>Get User by Username </header>
|
||||
<text><c>GET /users/<user.username></c></text>
|
||||
<text>
|
||||
Returns a <a href="#user-object">user object</a> for a given username,
|
||||
doesn't require any authorization.
|
||||
</text>
|
||||
</article>
|
||||
Reference in New Issue
Block a user