API Docs

Welcome to Freya's API documentation! Freya is built off of a CRUD (create, read, update, delete) API structure. You can pretty much do anything and everything to Freya via the API with some exclusions for security.

The following text blocks below are to ease some tensions on potential edge cases to common confusions. Aswell as documentation on how the API works.

Versioning

Freya's API versioning is pretty simple. When accessing the API you will do so by using a path similar to this: https://freya.test/api however you will want to use the versioning when using any API routes, which will make your path look like this: https://freya.test/api/v1. This is to prevent breaking from updates, etc... The API may change at anytime but the previous version will always stay the same before the next version is introduced, if it's ever introduced.

Authorization

Freya's API is completely locked behind an Authorization header. The authorization header will only accept valid keys generated on the site (you can find out how to generate them here), as well as a valid IP address (if specified).

To access the API all you simply do is pass a header named Authorization with the value being the key. If IP whitelisting is enabled on this key it will only be accessible to the IP it was set to. Your authorization key may look something like this: Authorization: KEY_HERE

Responses

The API will return responses based on the action you've requested from the API. All of the responses the API sends back are JSON, so please make sure to set your Content-Type header to application/json!

Here is a list of the following responses the API will return back:

401 Unauthorized Example Response:

{
  "response": "Bad Authorization",
  "client": "127.0.0.1",
  "user_agent": "insomnia\/2020.3.3",
  "monki_fax": "Monkeys are loud, very loud! You can hear the booming sound of monkeys from about 1 mile (1.6 km) away."
}

200 OK Will return if an action was executed properly or the page returned back with no problems.

201 Created Will return if a record was created.

400 Bad Request Usually executed if an input validator fails:

POST:https://freya.test/api/v1/bans/attempts/create

{
  "ban_id": "",
  "steam_id": "",
  "ip": "127.0.0.1"
}

Response 400 Bad Request:

[
  {
    "steam_id": [
      "The steam id field is required."
    ]
  }
]

404 Not Found Should be obvious right?

500 Server Error Something went wrong and caused Freya to error, it will be logged. Any database actions done inside the 500 will be rolled back to prevent corruption.

Dates & Timings

Dates are something very important in the suite, obviously you want to have a date for your duration, ban creation, etc... Freya utilizes the PHP Carbon library for dates, it's an insanely powerful library that can do a lot with timings. Pretty much all date inputs are passed through Carbon::parse() this method can parse all sorts of strings and dates such as: tomorrow, 3 days 2 hours 4 minutes 20 seconds, 5 hours, last day of May, etc...

With the parser you can basically convert any time value, whether it be a timestamp or datetime. Although please note with unix timestamp do not use a string run it through the parser as an int.

Payloads

So far you can pretty much use any data type you wish for Payloads. So far I've tested the API with Form data as-well as JSON data. As long as the inputs are correct it should accept pretty much any Payload data type.

Casts

Some values are casted into strings such as SteamIDs. Unfortunately due to limitations with JSON we cannot return an int value for SteamID 64 so we have to cast it to a string. We recommend not using an int value for sending SteamID 64 as it may provide incorrect information due to JSON limitations, if you cast it as a string it should work just fine.

Booleans

Booleans are used to determine if something is true or false. There is something to note with booleans however: if you are using a Form method you cannot use true or false - you will have to use 1 or 0.

JSON payloads so far can accept true and false but from testing Form payloads you will be forced to use 1 or 0 sadly.

Route Parameters

Route parameters are indicated by {} these curly brackets, most route parameters will be something like {id}. This indicates the id value on the record, so if you wanted to get a ban that has the ID of 4 you would put 4 into the https://freya.test/api/v1/bans/{id} value and it would look like this https://freya.test/api/v1/bans/4 in your url resolver.