tidepool-org/tidepool-org.github.io — pull request #36 by nicolashery (2014-10-03 21:12:36+00:00)
Title: Update invitations API docs

A first update to the invitations API docs to match implementation (and in some places future implementation, for example checking if a user is already a member when sending a new invite).

@jh-bate @kentquirk Could you take a look at the PR, as well as the following comments? Forgive me if these comments are a bit overwhelming, but it's all the things that came up when I was using and testing the API locally today, so it's a bit of a "brain dump". We can take things one at a time, in whatever order, and I'm happy to discuss specifics over a live chat :) Thanks!

## General

**(A1)** Next time (ex: child accounts), do you think it would make sense for the developer implementing the API to update these docs as she develops the API? To do this particular piece, I had to get the platform running locally, load some data, make API calls testing different scenarios, sometimes mess with the data in Mongo, etc. I'm happy to do testing of an API, but there was a lot of work getting set up and in some parts required me to understand implementation details, which I think is what we're trying to avoid with this document...

**(A2)** Should we be using a `type` called `careteam_invitation`? (I know "care team" if a word we're trying to be careful with, like "patient"). Maybe just `invitation`, or if we imagine we might have different types of invitations, `group_invitation` or `access_invitation`?

**(A3)** With each API call, should we always get back the whole invitation(s) object(s)? Specifically I'm thinking of the `userId` attribute (see below, more about that one), which could allow the client to know if a particular email is in the system or not. Also `status`, `modified`, which could potentially allow the client to know if an invite was `declined`?

**(A4)** This is me being a bit "OCD", but it would be nice if we could follow a consistent naming convention (`camelCase`, `alllowercase`, `snake_case`, etc.) in the data stored in Mongo and the JSON being sent back and forth. Lately, I've seen `userId` used in Hydrophone, but everywhere else it's `userid`. Also, I see `touser`, but other fields are camel case like `creatorId`. What do you guys think? We don't necessarily need to go back and change, but for future things?