diff --git a/docs/content/overview/_index.md b/docs/content/overview/_index.md index ec6bc89..d75848f 100644 --- a/docs/content/overview/_index.md +++ b/docs/content/overview/_index.md @@ -3,3 +3,16 @@ title: Overview anchor: overview weight: 5 --- + + +## What this section does not cover + +Details on implementation are found under: + +* [JSON API Endpoints](#endpoints) + +Details what endpoints are available to send/receive data through. + +* [Structures](#structures) + +Details what kind of data is sent back and forth between clients and servers. diff --git a/docs/content/overview/connections.md b/docs/content/overview/connections.md new file mode 100644 index 0000000..9aa2428 --- /dev/null +++ b/docs/content/overview/connections.md @@ -0,0 +1,13 @@ +--- +title: Connections +anchor: conns +weight: 7 +--- + + +Most servers will likely run on one of three ports, `80` for basic HTTP, `443` for secure HTTP traffic, or `4536` for most others. +If using a _special port_ then servers should expect _user applications_ to specify the port. + +For connections over SSH or other protocols it really is up to server owners to let new users know about this important detail. +SSH based servers are not discouraged, in fact they are highly _encouraged_ to exist and operate :^) + diff --git a/docs/content/overview/protocol.md b/docs/content/overview/protocol.md index 978e41a..fb805ea 100644 --- a/docs/content/overview/protocol.md +++ b/docs/content/overview/protocol.md @@ -1,28 +1,9 @@ --- -title: Protocol -anchor: protocol +title: Introduction +anchor: intro weight: 6 --- -## What this section covers - -What one should expect when attempting to implement a server/client compliant -with the Freechat protocol. - -## What this section does not cover - -Details on implementation are found under: - -* [JSON API Endpoints](#endpoints) - -Details what endpoints are available to send/receive data through. - -* [Structures](#structures) - -Details what kind of data is sent back and forth between clients and servers. - -## Overview Content - The Freechat protocol is based on HTTP and currently outlines a _json-based_ API hereafter referred to as just, the "JSON API". Due to the standards already in place with HTTP and JSON it is safe to assume @@ -32,9 +13,3 @@ that this protocol be more of an outline for what HTTP endpoints to have and wha * Data structures are also outline under the [structures](#structures) section. -Most servers will likely run on one of three ports, `80` for basic HTTP, `443` for secure HTTP traffic, or `4536` for most others. -If using a _special port_ then servers should expect _user applications_ to specify the port. - -For connections over SSH or other protocols it really is up to server owners to let new users know about this important detail. -SSH based servers are not discouraged, in fact they are highly _encouraged_ to exist and operate :^) - diff --git a/docs/content/overview/sec.md b/docs/content/overview/sec.md new file mode 100644 index 0000000..655a7e9 --- /dev/null +++ b/docs/content/overview/sec.md @@ -0,0 +1,29 @@ +--- +title: Security +anchor: sec-overview +weight: 8 +--- + +**DO NOT STORE PLAINTEXT SECRETS**. For developers that aren't _rarted_ this +isn't hard but if you think about doing this, don't. + +With the secret value compromised there is nothing you can do(that I encourage anyways) +to tell if that account has been stolen. +If for some reason you(an admin) believes an account has been stolen, then +lock the account by removing its permissions. + +JSON Web Tokens are used as a kind of session/cookie system as user applications +are not assumed to be browsers ever. +Freechat servers do not assume user apps to be browser to give people maximum +freedom in both application choice and developers freedom to use whatever hipster +libraries/frameworks languages they want. + +* JWT's should **never** last more than 1 week + * 24 hours is fine but they should **always expire** + +* JWT's should **always** be re assignable with the /login route + +>I hate jwt + +Sucks that what we use until a more flexible standard is designed/developed/doc'd. + diff --git a/docs/content/overview/user-apps.md b/docs/content/overview/user-apps.md new file mode 100644 index 0000000..b9807dd --- /dev/null +++ b/docs/content/overview/user-apps.md @@ -0,0 +1,51 @@ +--- +title: User Applications +anchor: user-overview +weight: 9 +--- + +As long as the application is ready to deal with receiving data in the forms +specified in [the structures section](#structures). + +App developers should keep in mind that data received is nearly always JSON. +The only exception is with empty body responses. + +For this reason there is really two things to look for on server response: + +1. HTTP Status Code + +2. `Content-Type` header which if present is `application/json`; signifying +the body contains some JSON data. + +It's safe to assume that if this isn't present the HTTP body should be ignored. + +## Authorizing + +To authorize on most routes you need to put the following in the query string: + +* `id` - The user id for that server + +* `jwt` - JSON web token + * It's suggested that this be refreshed when you application starts to not + get hit with random HTTP:400's on accident + +To get a valid JSON web token to use check the `/login` route details under the +[authorization section](#auth-ep). + +## Making requests + +Most request data goes in the query string however, large payloads are the exception. +For example the `/messages/send` expects the content of the message to be +sent in the request body while the query string is used to describe what the +request body is supposed be. + +* Request Headers + + Are not required since Freechat servers assume the worst of clients +so they don't bother ever looking there. + Save yourself the bandwidth and don't put anything there(or do idc tbh). + +* Response Headers + + As of now the only thing to look for is a present `Content-Type: application/json`. +