rest.md

Option 1: Distinguishing with URIs/separate endpoints

POST /users/:userId/vaults # create vault with user ownership
{
  ...vaultpayload
}

POST /teams/:userId/vaults # create vault with team ownership
{
  ...vaultpayload
}

POST /vaults  # create account vault
{
  ...vaultpayload
}

PROS:

• don't have to specify type in the Payload

CONS:

• a bit inconsistent in terms of
• how do we crud?
• keep using those signatures? (duplication)
• CRUD using the generic and already existing /vaults endpoints (inconsistency)
• what should return look like when I list all vaults for account? possibly like this

[
  {
    ...vaultpayload
    type: user
    user_ownership: {
      user_id: 123
    }
  },
  {
    ...vaultpayload
    type: user
    team_ownership: {
      team_id: 123
    }
  },
  {
    ...vaultpayload
    type: account
    team_ownership: {
      team_id: 123
    }
  }
]

Option 2: Using Payload to specify ownership and types

POST /vaults # create vault with user ownership
{
  ...vaultpayload
  type: user,
  user_ownership: {
    user_id: 123
  }
}

POST /vaults # create vault with team ownership
{
  ...vaultpayload
  type: team,
  team_ownership: {
    team_id: 123
  }
}

POST /vaults  # create account vault
{
  ...vaultpayload,
  type: account
}

PROS:

• consistent endpoints
• consistent payloads

CONS:

• have to specify "type" in the Payload
• structure looks artificial, maps almost 1:1 to the entities we defined (perhaps make user_id and team_id as a root property? maybe also during creation?)
• not sure how to manipulate ownerships, we only have PATCH method on vaults, and it should NOT manipulate ownerships

Option 3: CRUD ALL THE THINGS!!!

POST /vaults/:vaultId/userOwnership/:userId # create userOwnership
PUT /vaults/:vaultId/userOwnership/:anotherUserId # change userOwnership
DELETE /vaults/:vaultId/userOwnership/:userId # change userOwnership

or something similar (userId might be in the payload, not in URL, for those who claim POST without payload is not a true POST)

PROS:

• fine graned control over ownerships (if at all needed)

CONS:

• we don't want a service be REST wrapper around entities (tm)
• ownerships still need to be present for filtering and in the output

QUESTIONS

• do we need ownership manipulation? Like delete ownership from a vault, or do we achieve it by deleting a vault and creating new one with new ownership
• which of the approaches look better? I personally prefer Option 2 and it's perfect if don't need ownership manipulation