REST API usage is unclear

[gudvinr]

While lurking through API docs I found number of issues which cause frustration on how to use it.
I will list them there to resolve. It should be a matter of more detailed explanation and nothing more.

• [ ] API browser does not contain login endpoint in the list while documentation mentions it
• [ ] Documentation is very unclear on how to make modifying requests (such as POST/PATCH/ etc). I guessed from OPTIONS request that you can take fields from there but it is not clear from documentation that I must extract this information from here. Few examples:
  • [ ] Specifically, Authentication section says "Send a username and password" but it does not explain how.
    Is it Basic HTTP auth?
    Is it post request with application/x-www-form-urlencoded or application/json?
    Is it GET request with query parameters?
    OPTIONS request makes me suggest that you must use POST with json payload and corresponding string fields.
  • [ ] Date format (e.g. within weightentry endpoint) is unspecified.

I kinda can guess answers to these questions but it makes hard to average folks to use API like that.
Putting a little effort in research is better than putting a lot of effort since you can spend more time on developing something using this API instead of figuring out how to use it.

[rolandgeider]

The API docs are... well, not the best. It's definitely in my TODO list!

[rolandgeider]

Another TODO: write a small guide on how to create a workout or nutritional plan over the api (which objects depend on what, etc)