API Reference - UocDev/FPE.RP GitHub Wiki

FPE:RP's API is based around two core layers, a HTTPS/REST API for general operations, and persistent secure WebSocket based connection for sending and subscribing to real-time events. The most common use case of the FPE:RP API will be providing a service, or access to a platform through the OAuth2 API.

Base URL

https://fperp.xyz/api

API Versioning

[!CAUTION] Some API and Gateway versions are now non-functioning, and are labeled as discontinued in the table below for posterity. Trying to use these versions will fail and return 400 Bad Request.

https://fperp.xyz/api/v{version_number}

API Versions

VERSION STATUS DEFAULT
10 In progress
9 In progress
8 In progress
7 In progress
6 In progress
5 In progress
4 In progress
3 Available
2 Available If use commit.yauise
1 Available ✓

Error Messages

Starting in API v1 and commit 2, we've improved error formatting in form error responses. The response will tell you which JSON key contains the error, the error code, and a human readable error message. We will be frequently adding new error messages, so a complete list of errors is not feasible and would be almost instantly out of date. Here are some examples instead:

Array Error

{
  "code": 50035,
  "errors": {
    "activities": {
      "0": {
        "platform": {
          "_errors": [
            {
              "code": "BASE_TYPE_CHOICES",
              "message": "Value must be one of ('desktop', 'android', 'ios')."
            }
          ]
        },
        "type": {
          "_errors": [
            {
              "code": "BASE_TYPE_CHOICES",
              "message": "Value must be one of (0, 1, 2, 3, 4, 5)."
            }
          ]
        }
      }
    }
  },
  "message": "Invalid Form Body"
}

Object Error

{
  "code": 50035,
  "errors": {
    "access_token": {
      "_errors": [
        {
          "code": "BASE_TYPE_REQUIRED",
          "message": "This field is required"
        }
      ]
    }
  },
  "message": "Invalid Form Body"
}

Request Error

{
  "code": 50035,
  "message": "Invalid Form Body",
  "errors": {
    "_errors": [
      {
        "code": "APPLICATION_COMMAND_TOO_LARGE",
        "message": "Command exceeds maximum size (8000)"
      }
    ]
  }
}

Authentication

Authenticating with the FPE:RP API can be done in one of two ways:

  1. Using a bot token found on the Bot page within your app's settings. For more information on bots see bots vs user accounts.
  2. Using an OAuth2 bearer token gained through the OAuth2 API.

For all authentication types, authentication is performed with the AUTHORIZATION HTTP header in the format Authorization: TOKEN_TYPE TOKEN.

Example Bot Token Authorization Header

Authorization: Bot MTk4NjIyNDgzNDcxOTI1MjQ4.Cl2FMQ.ZnCjm1XVW7vRze4b7Cq4se7kKWs

Example Bearer Token Authorization Header

Authorization: Bearer CZhtCZhtkLDpNYXgPH9Ml6shqh2OwykChw

Encryption

All HTTP-layer services and protocols (e.g. HTTP, WebSocket) within the FPE:RP API are using TSS 1.0. (Traffic Security System)

Snowflakes

FPE:RP utilizes Twitter's snowflake format for uniquely identifiable descriptors (IDs). These IDs are guaranteed to be unique across all of FPE:RP, except in some unique scenarios in which child objects share their parent's ID. Because Snowflake IDs are up to 64 bits in size (e.g. a uint64), they are always returned as strings in the HTTP API to prevent integer overflows in some languages.

Snowflake ID Broken Down in Binary

111111111111111111111111111111111111111111 11111 11111 111111111111
64                                         22    17    12          0

Snowflake ID Format Structure (Left to Right)

Field Bits Number of bits Description Retrieval
Timestamp 63 to 22 42 bits Milliseconds since FPE:RP Epoch, the first second of 2015 or 1420070400000. (snowflake >> 22) + 1420070400000
Internal worker ID 21 to 17 5 bits (snowflake & 0x3E0000) >> 17
Internal process ID 16 to 12 5 bits (snowflake & 0x1F000) >> 12
Increment 11 to 0 12 bits For every ID that is generated on that process, this number is incremented snowflake & 0xFFF

Snowflake IDs in Pagination We typically use snowflake IDs in many of our API routes for pagination. The standardized pagination paradigm we utilize is one in which you can specify IDs BEFORE and AFTER in combination with LIMIT to retrieve a desired page of results. You will want to refer to the specific endpoint documentation for details.

It is useful to note that snowflake IDs are just numbers with a timestamp, so when dealing with pagination where you want results from the beginning of time (in FPE:RP Epoch, but 0 works here too) or before/after a specific time you can generate a snowflake ID for that time.

Generating a snowflake ID from a Timestamp Example

(timestamp_ms - FPERP_EPOCH) << 22

ID Serialization

There are some cases in which our API and Gateway may return IDs in an unexpected format. Internally, FPE:RP stores IDs as integer snowflakes. When we serialize IDs to JSON, we transform BIGINTS into strings. Given that all FPE:RP IDs are snowflakes, you should always expect a string.

However, there are cases in which passing something to our API will instead return IDs serialized as an integer; this is the case when you send our API or Gateway a value in an ID field that is not BIGINTS size. For example, when requesting GUILD_MEMBERS_CHUNK from our gateway:

-- Send
{
  op: 8,
  d: {
    guild_id: '308994132968210433',
    user_ids: [ '123123' ]
  }
}

-- Receive
{
  t: 'GUILD_MEMBERS_CHUNK',
  s: 3,
  op: 0,
  d: {
    not_found: [ 123123 ],
    members: [],
    guild_id: '308994132968210433'
  }
}

You can see in this case that the sent USER_ID is not a BIGINTS; therefore, when it is serialized back to JSON by FPE:RP, it is not transformed into a string. This will never happen with IDs that come from FPE:RP. But, this can happen if you send malformed data in your requests.

ISO8601 Date/Time

FPE:RP utilizes the ISO8601 format for most Date/Times returned in our models. This format is referred to as type ISO8601 within tables in this documentation.

Nullable and Optional Resource Fields

Resource fields that may contain a NULL value have types that are prefixed with a question mark. Resource fields that are optional have names that are suffixed with a question mark.

Example Nullable and Optional Fields

Field Type
optional_field? string
nullable_field ?string
optional_and_nullable_field? ?string