Merge pull request #76 from the-grid/collaboration

Initial collab docs

blueprint/api.apib

@@ -271,6 +271,47 @@ A site can be updated to use any of the redesigns by publishing it. This will tr
 
 + Response 200 (text/html)
 
+## Collaboration [/site/{id}/collaborator]
+
+### Listing collaborators [GET]
+
+Site owner can list the site's collaborators.
+
++ Parameters
+  + id (required, string) - Site UUID
+
++ Response 200 (application/json)
+
+  + Body
+
+      ```
+      [
+      <!-- include(examples/collaborator-accepted-by-url.json) -->
+      ]
+      ```
+
+
+### Inviting a new collaborator [POST]
+
+Site owner can invite new collaborators to a site. Collaborators can be invited either by email or by URL of a Grid site.
+
++ Parameters
+  + id (required, string) - Site UUID
+
++ Request (application/json)
+
+  + Body
+
+      ```
+      <!-- include(examples/collaboratorinvite-email.json) -->
+      ```
+
+  + Schema
+
+      ```
+      <!-- include(full-schema/collaboratorinvite.json) -->
+      ```
+
 # Group Content Management
 
 ## Share [/share]

examples/collaborator.yml

@@ -0,0 +1,8 @@
+-
+  _valid: true
+  _name: "accepted-by-url"
+  _data:
+    id: 5
+    collaborator: 'http://bergie.today/'
+    accepted: true
+    rejected: false

examples/collaboratorinvite.yml

@@ -0,0 +1,31 @@
+-
+  _valid: true
+  _name: 'email'
+  _data:
+    email: '[email protected]'
+    name: 'Test User'
+    subject: 'Join my cool site'
+    sender: 'A Grid User'
+-
+  _valid: true
+  _name: 'url'
+  _data:
+    url: 'https://example.net'
+-
+  _valid: false
+  _name: 'url-and-email'
+  _data:
+    url: 'https://example.net'
+    email: '[email protected]'
+    name: 'Test User'
+-
+  _valid: false
+  _name: 'invalid-email'
+  _data:
+    email: 'foobar'
+    name: 'Test User'
+-
+  _valid: false
+  _name: 'invalid-url'
+  _data:
+    url: 'Cool Site'

schemata/collaborator.yaml

@@ -0,0 +1,28 @@
+---
+id: collaborator.json
+"$schema": "http://json-schema.org/draft-04/schema"
+title: Site collaborator
+description: ""
+type:
+- object
+properties:
+  id:
+    type: integer
+  collaborator:
+    describe: "Collaborator label"
+    oneOf:
+      - { "$ref": "base.json#/definitions/url" }
+      - { "$ref": "base.json#/definitions/email" }
+  accepted:
+    describe: "Whether collaborator has accepted the invitation"
+    type: boolean
+  rejected:
+    describe: "Whether collaborator has rejected the invitation"
+    type: boolean
+  created_at:
+    type: string
+    format: 'date-time'
+  updated_at:
+    oneOf:
+    - { type: 'null' }
+    - { type: 'string', format: 'date-time' }

schemata/collaboratorinvite.yaml

@@ -0,0 +1,28 @@
+---
+id: collaboratorinvite.json
+"$schema": "http://json-schema.org/draft-04/schema"
+title: Site collaborator invitation
+description: ""
+type:
+- object
+properties:
+  url:
+    description: "Grid site URL to invite the owner as collaborator"
+    "$ref": "base.json#/definitions/url"
+  email:
+    description: "Email address of collaborator to invite"
+    "$ref": "base.json#/definitions/email"
+  name:
+    description: "Name of the person to invite"
+    type: string
+  subject:
+    description: "Subject of the invitation"
+    type: string
+  sender:
+    description: "Invitation sender name"
+    type: string
+additionalProperties: false
+
+oneOf:
+  - { required: [url] }
+  - { required: [email, name] }