Donut Team Community API v2.0

This book contains information about the current version of the Donut Team Community API.

Getting Started

Introduction

Oh wow, you found our Community API. This API allows developers to retrieve information using HTTP requests. These pages are dedicated to helping creators make awesome content that make the community a better place.

Tips on reading this documentation

  • Endpoints denoted with an asterisk (*) require an API Key.
  • Endpoints denoted with an exclamation mark (!) require both an API Key and user authentication.
  • Endpoints denoted with one of the two previous markings matched with a question mark (?) support connecting without an API Key or user authentication, however may be limited without it.

Changes from version 1.0

  • Specifying a "Format" using a query argument will now tell the API to respond in a legacy format.
    • The YAML and INI formats are not allowed to be specified using the "Format" query argument.
  • Specifying "ExcludeNewData" will try to exclude any new data we associate with this API.
  • The "ProfileLookup" endpoint is now called "User". ProfileLookup can still be used, but is deprecated.
  • The "User" endpoint now returns new data
    • "JoinDateDisplay" using "j F Y h:i:s a (T)" format. To control it yourself, you can use the UNIX timestamp returned as "JoinDate".
    • "KarmaScore". This number will not return a value less than 0, even when the user's karma score is below 0.
    • "IsPage" will return a boolean value of if the account is a page or not.
    • "VerifiedStatus" will return an integer 0-4 of a user's verified status.
  • In XML, integer values will now be returned as an attribute.
  • In XML, boolean values will now be returned as an attribute of 0 or 1.
  • In XML, the "User" endpoint now returns each user as a "User" node instead of a "Data" node.

Authorisation Identifier

This section is a work in progress.

The API Authorisation Identifier is a 64 character long string that is used to allow applications access to a user's Donut Team account.

Frequently Asked Questions:

When does the API turn on?

We're currently developing this API, so it is currently unavailable.

Does this replace Donut Team Community API 1.0? Will 1.0 be disabled?

The old API will be turned off immediately once we release the new API. However to ensure all legacy code works moving forward, we've created a backwards compatibility layer that will allow all 1.0 requests be respected and served the same exact way your code was written to expect. At this time, we have no intention to ever turn off the compatibility layer, however new endpoints will not explicitly support the old format.

Supported Formats

The Donut Team Community API supports returning data in 4 formats.

Examples

All examples demonstrate the Default endpoint in each returned format.

JSON Default
GET https://api.donutteam.com/Default.json
{
    "Version": "2.0",
    "Endpoint": "Default",
    "Method": "GET",
    "Accessor": {
        "UserAgent": "Mozilla\/5.0 (Windows NT 6.3; Win64; x64) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/71.0.3578.98 Safari\/537.36",
        "IP": "[REDACTED]",
        "CC": "US"
    },
    "FullPath": "https:\/\/api.donutteam.com\/Default.json",
    "Path": [
        "Default"
    ]
}
XML
GET https://api.donutteam.com/Default.xml
<?xml version="1.0" encoding="utf-8"?>
<DonutTeam>
  <Version>2.0</Version>
  <Endpoint>Default</Endpoint>
  <Method>GET</Method>
  <Accessor>
    <UserAgent>Mozilla/5.0 (Windows NT 6.3; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36</UserAgent>
    <IP>[REDACTED]</IP>
    <CC>US</CC>
  </Accessor>
  <FullPath>https://api.donutteam.com/Default.xml</FullPath>
  <Path>
    <Data>Default</Data>
  </Path>
</DonutTeam>
YAML
GET https://api.donutteam.com/Default.yaml
---
Version: "2.0"
Endpoint: Default
Method: GET
Accessor:
    UserAgent: >
        Mozilla/5.0 (Windows NT 6.3; Win64; x64) AppleWebKit/537.36
        (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36
    IP: [REDACTED]
    CC: US
FullPath: https://api.donutteam.com/Default.yaml
Path:
    - Default
INI

INI implementation is wildly different across platforms and libraries used. We highly recommend using one of the other four return formats if you're uncertain.

GET https://api.donutteam.com/Default.ini
Version="2.0"
Endpoint="Default"
Method="GET"
[Accessor]
UserAgent="Mozilla/5.0 (Windows NT 6.3; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36"
IP="[REDACTED]"
CC="US"
FullPath="https://api.donutteam.com/Default.ini"
[Path]
0="Default"

Example request

GET https://api.donutteam.com/Default.xml
<DonutTeam>
	<Version>2.0</Version>
	<Accessor>Mozilla/5.0 (Windows NT 6.3; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36</Accessor>
	<Method>GET</Method>
	<Event>NoEndpoint</Event>
	<Path>
		<Data>Default</Data>
	</Path>
</DonutTeam>

Unsorted Endpoints

Unsorted Endpoints

Default

The Default endpoint provides information about the API and your request. If no other endpoint matches your request, this endpoint will be served.

Endpoint

https://api.donutteam.com/Default.json

Arguments

This endpoint takes no arguments.

Examples

All examples demonstrate the Default endpoint in each returned format.

JSON Default
GET https://api.donutteam.com/Default.json
{
    "Version": "2.0",
    "Endpoint": "Default",
    "Method": "GET",
    "Accessor": {
        "UserAgent": "Mozilla\/5.0 (Windows NT 6.3; Win64; x64) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/71.0.3578.98 Safari\/537.36",
        "IP": "[REDACTED]",
        "CC": "US"
    },
    "FullPath": "https:\/\/api.donutteam.com\/Default.json",
    "Path": [
        "Default"
    ]
}
XML
GET https://api.donutteam.com/Default.xml
<?xml version="1.0" encoding="utf-8"?>
<DonutTeam>
  <Version>2.0</Version>
  <Endpoint>Default</Endpoint>
  <Method>GET</Method>
  <Accessor>
    <UserAgent>Mozilla/5.0 (Windows NT 6.3; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36</UserAgent>
    <IP>[REDACTED]</IP>
    <CC>US</CC>
  </Accessor>
  <FullPath>https://api.donutteam.com/Default.xml</FullPath>
  <Path>
    <Data>Default</Data>
  </Path>
</DonutTeam>
YAML
GET https://api.donutteam.com/Default.yaml
---
Version: "2.0"
Endpoint: Default
Method: GET
Accessor:
    UserAgent: >
        Mozilla/5.0 (Windows NT 6.3; Win64; x64) AppleWebKit/537.36
        (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36
    IP: [REDACTED]
    CC: US
FullPath: https://api.donutteam.com/Default.yaml
Path:
    - Default
INI
GET https://api.donutteam.com/Default.ini
Version="2.0"
Endpoint="Default"
Method="GET"
[Accessor]
UserAgent="Mozilla/5.0 (Windows NT 6.3; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36"
IP="[REDACTED]"
CC="US"
FullPath="https://api.donutteam.com/Default.ini"
[Path]
0="Default"

User Profile Endpoints

User Profile Endpoints

User!?

This API endpoint supports being used anonymously, however provides more functionality when a user authenticates.

The User endpoint provides basic information about a user such as their username, identifier, display name, rank and join date.

Endpoint

https://api.donutteam.com/User.json

Arguments

As with the rest of the API, arguments are passed as part of the URI separated by forward slashes.

https://api.donutteam.com/{Endpoint}/{Method}/{Data}/{Data}/{Data}

Endpoint (Required)

The endpoint's name, "User," followed by the format of your choosing.

Method (Optional)

id A unique integer value associated with each account. If a method is not defined, id will be used by default.
username A unique string value used as an identifier associated with all users.
discordId A snowflake value that gets associated with all users who connect their Discord account to the Donut Team service. 
session A Donut Team Authorisation Session Identifier.
token Deprecated This has been deprecated and is only documented for internal use.

Data (Required)

The data associated with a user lookup. Only one is required, however an infinite amount is supported. This data will be returned as the key name of each object to make it easy to compare the data.

Example response

XML

GET https://api.donutteam.com/User.xml/username/jake/loren/lucasc190
<DonutTeam>
	<User Value="jake">
		<Id Value="1"/>
		<Username>jake</Username>
		<JoinDate Value="1363694400"/>
		<JoinDateDisplay>19 March 2013 08:00:00am (EDT)</JoinDateDisplay>
		<VerifiedStatus Value="4"/>
		<KarmaScore Value="395"/>
		<Rank>5</Rank>
		<IsConfirmed Value="1"/>
		<Banned Value="0"/>
		<DisplayName>Jake Andreøli</DisplayName>
	</User>
	<User Value="loren">
		<Id Value="2"/>
		<Username>loren</Username>
		<JoinDate Value="1363694400"/>
		<JoinDateDisplay>19 March 2013 08:00:00am (EDT)</JoinDateDisplay>
		<VerifiedStatus Value="4"/>
		<KarmaScore Value="352"/>
		<Rank>5</Rank>
		<IsConfirmed Value="1"/>
		<Banned Value="0"/>
		<DisplayName>Loren Goodwin</DisplayName>
	</User>
	<User Value="lucasc190">
		<Id Value="395"/>
		<Username>lucasc190</Username>
		<JoinDate Value="1396234333"/>
		<JoinDateDisplay>30 March 2014 10:52:13pm (EDT)</JoinDateDisplay>
		<VerifiedStatus Value="4"/>
		<KarmaScore Value="0"/>
		<Rank>5</Rank>
		<IsConfirmed Value="1"/>
		<Banned Value="0"/>
		<DisplayName>Lucas Cardellini</DisplayName>
	</User>
</DonutTeam>

JSON

GET https://api.donutteam.com/User.json/username/jake/loren/lucasc190
{
    "jake": {
        "Id": 1,
        "Username": "jake",
        "JoinDate": 1363694400,
        "JoinDateDisplay": "19 March 2013 08:00:00am (EDT)",
        "VerifiedStatus": 4,
        "KarmaScore": 395,
        "Rank": 5,
        "IsConfirmed": true,
        "Banned": false,
        "DisplayName": "Jake Andre\u00f8li"
    },
    "loren": {
        "Id": 2,
        "Username": "loren",
        "JoinDate": 1363694400,
        "JoinDateDisplay": "19 March 2013 08:00:00am (EDT)",
        "VerifiedStatus": 4,
        "KarmaScore": 352,
        "Rank": 5,
        "IsConfirmed": true,
        "Banned": false,
        "DisplayName": "Loren Goodwin"
    },
    "lucasc190": {
        "Id": 395,
        "Username": "lucasc190",
        "JoinDate": 1396234333,
        "JoinDateDisplay": "30 March 2014 10:52:13pm (EDT)",
        "VerifiedStatus": 4,
        "KarmaScore": 0,
        "Rank": 5,
        "IsConfirmed": true,
        "Banned": false,
        "DisplayName": "Lucas Cardellini"
    }
}
User Profile Endpoints

Profile!?

This is coming soon.

This API endpoint supports being used anonymously, however provides more functionality when a user authenticates.

User Profile Endpoints

Account!

This is coming soon.

This API endpoint requires authentication to be used.

Authentication Endpoints

Authentication Endpoints

RequestAuthentication*

This API endpoint requires authentication to be used.

The RequestAuthentication endpoint returns a URL to give to a user to authenticate with your application using Donut Team.

Endpoint

https://api.donutteam.com/RequestAuthentication.json

Arguments

As with the rest of the API, arguments are passed as part of the URI separated by forward slashes.

https://api.donutteam.com/{Endpoint}/{APIKey}

Endpoint (Required)

All valid:

  • RequestAuthentication.xml
  • RequestAuthentication.json

APIKey (Required)

Your application's API key.

Handling the response

Successful response

A successful response will return the following values:

Code This code is a temporary key that will be used to query if a user has authenticated with your app. You should re-query this code using CheckAuthenticateToken every 20 seconds while waiting for authentication. This code will expire after 15 minutes if it is not authenticated within that time.
Link The link you should open in the user's browser to allow authentication. This link will expire after 15 minutes if it is not authenticated within that time.

Error response

ErrorCode
An error code used for internal development purposes. Endpoint separated by two colons and then an incriminating number. This should be used when you want to handle the error yourself.
ErrorText
Error text to explain what is happening.

Errors

RequestAuthentication::1
RequestAuthentication::3
No API Public Key provided.
RequestAuthentication::2
Provided public key was not found.
We were unable to find your application's API in our database. You may have a mistake in the key you gave us.
RequestAuthentication::4
API does not have permission for request authentication.
Your application does not have the permission to request authentication.
RequestAuthentication::5
API understood your request but was unable to fulfill it.
An error occurred on our end that was irrecoverable.

Example response

XML

GET https://api.donutteam.com/RequestAuthentication.xml/ZOS8csheS8csheFqkLVFS8qkLVQDDudZK
<DonutTeam>
	<Code>tzes7_V56p2hq-OjrR3Ym1X9BLmMhkdBkTVV8C4Uco_nGw-mtVKRgQjwxHHRQnVc</Code>
	<Link>https://donutteam.com/authoriseApp/ZOS8csheS8csheFqkLVFS8qkLVQDDudZK/tzes7_V56p2hq-OjrR3Ym1X9BLmMhkdBkTVV8C4Uco_nGw-mtVKRgQjwxHHRQnVc/1549811688</Link>
</DonutTeam>

JSON

GET https://api.donutteam.com/RequestAuthentication.json/ZOS8csheS8csheFqkLVFS8qkLVQDDudZK
{
    "Code": "3jXkcOOejTlgF-QgYFmxiqiVZOq3ReYeAAPgJODwYMNzk7i35TI3caziCE7f0Uz8",
    "Link": "https:\/\/donutteam.com\/authoriseApp\/ZOS8csheFqkLVQDDudZK\/3jXkcOOejTlgF-QgYFmxiqiVZOq3ReYeAAPgJODwYMNzk7i35TI3caziCE7f0Uz8\/1549811728"
}
Authentication Endpoints

CheckAuthenticateToken*

This is coming soon.

This API endpoint requires authentication to be used.

Authentication Endpoints

Deauthenticate!

This API endpoint requires authentication to be used.

The Deauthenticate endpoint provides the ability to remove access to a Donut Team Community API Authorisation Identifier.

Endpoint

https://api.donutteam.com/Deauthenticate.json

Arguments

As with the rest of the API, arguments are passed as part of the URI separated by forward slashes.

https://api.donutteam.com/{Endpoint}/{SessionToDeauthenticate}

Endpoint (Required)

All valid:

  • Deauthenticate
  • Deauthenticate.xml
  • Deauthenticate.json

SessionToDeauthenticate (Required)

An Authorisation Identifier that was given to you by a user giving you access to their account through the use of an API sign in.

Example response

XML

GET https://api.donutteam.com/Deauthenticate.xml/GwaFtgZ3lBL7b60ebVIejFkyA2X8W9WFXfoP3hhulj-hZkf889BcmxJaACCfm5IX
<DonutTeam>
	<Success Value="1"/>
</DonutTeam>

JSON

GET https://api.donutteam.com/Deauthenticate.json/GwaFtgZ3lBL7b60ebVIejFkyA2X8W9WFXfoP3hhulj-hZkf889BcmxJaACCfm5IX
{
    "Success": true
}

Possible responses:

Successful:

{
    "Success": true
}

Failed, you did not specify a session token:

{
    "Success": false,
    "Error": "A session token was not provided."
}

Failed, the session you provided was not valid or does not exist:

{
    "Success": false,
    "Error": "Session not valid"
}

Account Endpoints

Account Endpoints

Notifications!

Coming soon.

Account Endpoints

Subscribe!

This is coming soon.

This API endpoint requires authentication to be used.

Forum Endpoints

Play History Endpoints

Play History Endpoints

AwardBadge!

This is coming soon.

This API endpoint requires authentication to be used.