diff --git a/docs/content/overview/_index.md b/docs/content/overview/_index.md new file mode 100644 index 0000000..d75848f --- /dev/null +++ b/docs/content/overview/_index.md @@ -0,0 +1,18 @@ +--- +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 new file mode 100644 index 0000000..fb805ea --- /dev/null +++ b/docs/content/overview/protocol.md @@ -0,0 +1,15 @@ +--- +title: Introduction +anchor: intro +weight: 6 +--- + +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 +that this protocol be more of an outline for what HTTP endpoints to have and what kind of data is to be expected in exchanges. + +* Endpoints listed in the [JSON API Endpoints section](#endpoints). + +* Data structures are also outline under the [structures](#structures) section. + 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`. +