First Swagger API Spec

[James-Oswald]

We need to agree on what our API looks like for the minimum viable product, and then implement this in an API specification language so we're all on the same page. For the first version of the API spec, we should include basic user and game functionality (cosmetics et al can wait)

• [x] #14
• [ ] User Update Calls
• [ ] Gameplay calls
• [ ] Leaderboard calls

[akaric108]

We can get away with a lot of things for the REST API, at least with the /users/ stuff (which is what we need ASAP so we can start iterating) #2

Drafted this up (didn't want to deal with YAML), note ...(PUBLIC DATA) and ...(PUBLIC DATA) are just place holders for some additional data that we designate as public or private. Should be pretty straight-forward.

GET "/users/"
RETURN "username"_1, "username"_2, ..., "username"_n

POST "/users/{username}"
TAKING ...(PUBLIC DATA), "password", ...(PRIVATE DATA)
IF ALREADY EXISTS "/users/{username}"
  RETURN 418
ELSE
  RETURN ...(PUBLIC DATA), "password", ...(PRIVATE DATA)

GET "/users/{username}"
IF HEADER CONTAINS CORRECT "password" FOR "/users/{username}"
  RETURN ...(PUBLIC DATA), "password", ...(PRIVATE DATA)
ELSE
  RETURN ...(PUBLIC DATA)

PUT "/users/{username}"
TAKING ...(PUBLIC DATA), "password", ...(PRIVATE DATA)
IF HEADER CONTAINS CORRECT "password" FOR "/users/{username}"
  RETURN ...(PUBLIC DATA), "password", ...(PRIVATE DATA)
ELSE
  RETURN 403

DELETE "/users/{username}"
IF HEADER CONTAINS CORRECT "password" FOR "/users/{username}"
  RETURN 200
ELSE
  RETURN 403

A couple of discussion points.

• There is no log-in, and there is no log-out. I can't really think of a scenario where we absolutely need an interface like that, because that should be the clients responsibility and not the servers (anyways, the server would already be handling timeout's when somebody closes the app. You can think of that as you auto log-out). Would love to hear counter-examples.
• That also means we can just include the user's password in the header for authenticating. Obviously then HTTPS is a must (and hashing the passwords on the device would be nice).
• I'm still undecided about /users/{id} vs /users/{username}. The first pushes complexity onto the sign-up/log-in code, because it's possible for more than one ID to have the same username. The second, by it's nature, makes that state unrepresentable, but at the cost of making username changes complex. Since we're just looking for a minimal viable product, I think it's better if forego username changes.
• I also purposefully didn't mention recording the users e-mail, because we'd only need something like that for verification and password resets, which is a whole thing. I don't think we need that for a minimal viable product.
• There will be no debate on the use of HTTP 418 as a return code.

[James-Oswald]

From a discussion with Armin:

There is no log-in, and there is no log-out.

Strong dislike, I've never seen an architecture this, this also requires rehashing a password and querying a database to make sure its right for every request. Keep to sessions.

/users/{id} vs /users/{username}

I personally don't care, you guys can force unique usernames or not, thats up to yall

I also purposefully didn't mention recording the users e-mail, because we'd only need something like that for verification and password resets, which is a whole thing.

Good to build it into the api even if we're not supporting it yet

There will be no debate on the use of HTTP 418 as a return code.

ok lmao, i see no issue as long as client side handles it properly

[akaric108]

From a discussion with James (also last night):

I've never seen an architecture this

Me neither, it's novel. I'm still not fully convinced that we need a log-in and log-out, because...

this also requires rehashing a password and querying a database to make sure its right for every request.

No, it doesn't, because the client stores the hash and sends it to the servers which just has to associate it with a user, which is exactly what we'd be doing with sessions, but the distinction is the lack of "logged in" and "logged out" states. Dropping that makes us a touch more stateless.

I don't have a strong opinion either way though, but it depends on Rune for which model fits better into the distributed backend. I just proposed it because this is a mobile app, so it's unlikely that we will get clean disconnects (so logout will never be called), and I didn't want to think about cleaning up sessions.

Good to build it into the api even if we're not supporting it yet

Agreed, it's good to just have the data. (James also suggested collecting age and gender for analytics, which I also agree with).

[akaric108]

You know, somethings only occur to you while you're writing the code.

If everything is going to be actors underneath... Then why isn't our API just POST requests sending messages to these actors? These actors already need their own APIs for talking with each other, so why don't we save ourselves the work and simplify things by sharing a common API?

This proposal wont make it for demo 1, obviously, but integration moving faster than expected because of the great work that's been done by both the front-end and back-end teams, so I can toy with this in a branch later and have something we can talk about.