Documentation Update

[NathanBland]

The docs currently are pretty awful.

@keawade has started the wiki pages to update this, and it needs done.

Issue for tracking....

[keawade]

Documentation has been updated with all currently existing endpoints.

[keawade]

We need to update the documentation with the changes made to /api/feed.

[keawade]

We also need to add documentation for the /api/auth endpoint.

[NathanBland]

You said you covered existing endpoints! I believed you! :cry:

But the existing feed docs are correct.

[NathanBland]

Done.

[keawade]

The documentation for /api/auth doesn't match the rest of the docs.

[NathanBland]

Nor will it. There is not a resource that is matched for auth, and it was initially classified as a special api.

[keawade]

That's not the issue. The styling doesn't match.

[NathanBland]

In what way? It was copy pasted from lower items :thinking:

[keawade]

Expected (ish)

• POST /api/post
  • Requires body containing a username and password as strings. Creates a new user with the given username and password if no such user exists. Returns an object containing the username and auth token as a string for the created user.
  • UserObject

Actual

• POST /api/auth/signup
  • Expects a username and password in the body
  • Validates against UserObject collection, as no duplicates are allowed
  • Returns

username: <String>
token: <String>

[NathanBland]

The primary difference being how return is noted?

[keawade]

I think I'd like to do something like this:

• POST /api/post
  • Requires body containing a username and password as strings.
  • Creates a new user with the given username and password if no such user exists.
  • Returns the UserObject for the created user.

So a generic version would look like this:

• REST /path/to/endpoint
  • Requirements
  • What (if anything) it does
  • What it returns

[keawade]

I think we may also want to consider documenting possible failures beyond the standard 404s and such. So if we fail due to some business logic on the server, we return a 40x error with a message of You done messed up, etc.

[NathanBland]

All endpoints will return the error that caused the failure if they know what it is. (ie. validation error)

[NathanBland]

Also, if you add what you think each endpoint should follow as a skeleton with some explanation at the top, it could serve as a helpful tool. For both people visiting the api doc so they know what to expect, and for us to add future endpoints.

[NathanBland]

New api means docs need updated. #17