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" is 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, 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?

**(A5)** I noticed that in every API call, I need to provide the current logged-in user's `userid` to the URL. This feels a bit weird to me, because I'm sending along a `tidepool-session-token`, so the backend *should already know who I am*, since it has to check my authentication?

## Sending an invitation

**(B1)** The `modified` field has a value of `"0001-01-01T00:00:00Z"` on a new invite. Should it have a value which is equal to the `created` field?

**(B2)** If Mary (user `11`) sends an invite to `charles@example.com`, and that email is already tied to Charles' user `21`, the `touser` field in the Mongo DB doesn't get filled with `21` (but things seem to work, because if I fetch received invite from Charles' account, I see Mary's invite -- more on that later). As a consequence, the `userId` field in the JSON response is empty too.

**(B3)** Related to the comment above (and I haven't tested this so correct me if I'm wrong), imagine Mary sends an invite to `notauser@example.com`, and that email is not tied to any user. Then someone *signs up* as `notauser@example.com`, should the backend go through the invites and allocate any invites with that email address to this new `userid`?

**(B4)** Response code is `200 OK`. Should it be `201 Created`?

**(B5)** Mary sends an invite to `bob@example.com`, a new invite object is created with status `pending`. Mary tries to send another invite to the same email, gets a `409 Conflict`. This is good. Now, Bob accepts (or ignores) the invite, setting its status to `completed` (or `declined`). In both cases, if Mary tries to send another invite to `bob@example.com`, a *new invite object is created* (i.e. we have 2 invites in the DB for the same email, one is `completed`, the other `pending`). I would've expected a `409 Conflict` there too. Finally, if Mary decides to cancel the invite to `bob@example.com` (setting its status to `canceled`), and then tries to send a new one, it *should create a new invite*. **Summary**: existing `pending`, `completed`, `declined` -> `409 Conflict`; existing `canceled` -> `201 Created`

**(B6)** Could be nice to get a body back with the `409 Conflict`, as there could be two reasons for it, "invite already sent", "user already a member"? Might be a good time to settle on an error body convention. I had offered something like:

```javascript
{
  error: {
    name: "InvitationAlreadyExists",
    message: "An invitation to that email has already been sent"
  }
}
```

## Get sent or received invitations

**(C1)** What was spec'd was: **get sent** -> `GET /confirm/invite/:userid`, **get received**-> `GET /confirm/invitations/:userid` ([original API doc](https://github.com/tidepool-org/tidepool-org.github.io/blob/9b247b55a21dd70b7094899ebabddcc1f121a77c/_docs/tidepool-api.md#get-sent-invitations)). What seems to be implemented (based on [platform-client](https://github.com/tidepool-org/platform-client/blob/829f7182c379d42d42cc94a29c5504c481d7d449/index.js#L860)), is  **get sent** -> `GET /confirm/invite/:userid`, **get received**-> `GET /confirm/invitations/:email`. Why the change to query received invites by `email` (vs. `userid`)? Imagine an account with multiple emails registered to it (possible backend-wise), we would want to get all received invites for that account? Also, looking at [Hydrophone's code](https://github.com/tidepool-org/hydrophone/blob/77a197173286b7898e64bf4b201cd629ae1c4096/api/hydrophoneApi.go#L107), I'm a bit confused because the implementation looks like it's actually the inverse of what `platform-client` is doing, i.e. **get sent** -> `GET /confirm/invite/:email`, **get received**-> `GET /confirm/invitations/:userid`.

**(C2)** When querying for a *collection*, if there are no elements, I would expect a body with `[]` (allows you to JSON parse it and map over it, even if there are no elements). Right now we get an empty body. What do you think?

## Accept or dismiss an invitation

**(D1)** I noticed that we now need to provide a body to the request with `{key: <invitationKey>}` (was not in the spec). I'm completely ok with that, but my question would be: If I'm providing this key, unique to an invitation, why do I also need to provide `:userid` and `creatorId`?

## Cancel an invitation

**(E1)** The request implemented is now a `PUT` (vs the `DELETE` that was spec'd). I'm fine with that (might actually make more sense, since the invitation is merely flagged as `canceled`), but just wanted to point it out.
Yes, I had put that to try to be consistent with the vocabulary we use in the code and documentation. Doesn't mean the user will see that word (I think we actually show "Ignore" to the user).