Share - Huddle/huddle-apis GitHub Wiki

Summary

It is possible for a user to share a resource with a set of specified recipients.

The user can optionally share a resource directly with a list of email users, those email users will be invited to join Huddle if they are not already in Huddle. To use this feature you must also specify which team(s) the new email users should be invited to.

Status

Operation
Sharing a resource

Resources that support Sharing

Operations

Sharing a resource

If the resource supports sharing, it will advertise a link with @rel value of share. For example, to share a document, issue a POST request to the share URI. The request body should contain a list of recipients and an optional message.

The request may optionally include an X-Allow-Invalid-Recipients header, which should be true or false (these are case insensitive). It determines whether the share request should fail (returning a 400 BAD REQUEST) if any of the users cannot be shared with for some reason, or just return a 202 ACCEPTED to indicate that the share request will be sent to as many users as possible.

See the response details below for more information on what information is included in a 400 BAD REQUEST response.

All shared documents are audited and stored within the audit trail.

Example

Request (with a message)

POST /documents/123/share HTTP/1.1
Content-Type: application/vnd.huddle.data+xml
Authorization: OAuth2 frootymcnooty/vonbootycherooty
XML
<share>
    <link rel="recipient" href="..." />
    <link rel="recipient" href="..." />
    <link rel="recipient" href="..." />
    <message>Hey, take a look at this exhilarating TPS report!</message>
</share>
JSON
{
    "recipients" : [
        {
            "rel" : "recipient",
            "href" : "..."
        },{
            "rel" : "recipient",
            "href" : "..."
        },{
            "rel" : "recipient",
            "href" : "..."
        }
    ],
    "message" : "Hey, take a look at this exhilarating TPS report!"
}

Request (without a message)

POST /documents/123/share HTTP/1.1
Content-Type: application/vnd.huddle.data+xml
Authorization: OAuth2 frootymcnooty/vonbootycherooty
XML
<share>
    <link rel="recipient" href="..." />
    <link rel="recipient" href="..." />
    <link rel="recipient" href="..." />
</share>
JSON
{
    "recipients" : [
        {
            "rel" : "recipient",
            "href" : "..."
        },{
            "rel" : "recipient",
            "href" : "..."
        },{
            "rel" : "recipient",
            "href" : "..."
        }
    ]
}

Request (with invites to new users)

POST /documents/123/share HTTP/1.1
Content-Type: application/vnd.huddle.data+xml
Authorization: OAuth2 frootymcnooty/vonbootycherooty
XML
<share>
    <link rel="recipient" href="..." />
    <link rel="recipient" href="..." />
    <link rel="recipient" href="..." />
    <message>Hey, take a look at this exhilarating TPS report!</message>
    <invite>
       <teams>
         <link rel="self" href="..." />
         <link rel="self" href="..." />
       </teams>
       <emails>
         <email>[email protected]</email>
         <email>[email protected]</email>
       </emails>
    </invite>
</share>
JSON
{
    "recipients" : [
        {
            "rel" : "self",
            "href" : "..."
        },{
            "rel" : "self",
            "href" : "..."
        }
    ],
    "invite" : {
        "teams" : [
        {
            "rel" : "self",
            "href" : "..."
        },{
            "rel" : "self",
            "href" : "..."
        }],
        "emails": [ "[email protected]", "[email protected]" ]
    },
    "message" : "Hey, take a look at this exhilarating TPS report!"
}

Request (optional header)

POST /documents/123/share HTTP/1.1
Content-Type: application/vnd.huddle.data+xml
Authorization: OAuth2 frootymcnooty/vonbootycherooty
X-Allow-Invalid-Recipients: true

Properties

Name Description
message An optional message to attach to the share which the recipients will see. Max length is 5000 characters.
invite An optional element that allows the requester to share and invite new users into Huddle by email. The element contains the email addresses of the recipients and the team ids they will be invited to.

Link relations

Name Description
recipient The URI of a user with whom the resource should be shared.

Response

If successful the request will return a 202 ACCEPTED.

If the resource could not be shared with any of the recipients, the share will not take place and the response will return a 400 BAD REQUEST with a list of the recipients with whom the resource could not be shared.

If the message is longer than 5000 characters then the share will not take place and the response will return a 400 BAD REQUEST.

When email addresses are supplied in the request a 400 BAD REQUEST response is sent if:

  • any of the email addresses in the request are invalid
  • more than 300 email addresses are supplied
  • no teams are supplied
  • at least one of the teams provided must have permission to view the document

You will receive a link header to the share information resource.

Successful Response
HTTP/1.1 202 ACCEPTED
Content-Type: application/vnd.huddle.data+xml
Link: </notification/shares/5df96158-5f6c-4d7f-a716-7877ad92c560>;rel="share-information"
Failed Response
HTTP/1.1 400 BAD REQUEST
Content-Type: application/vnd.huddle.data+xml

<shareFailure>
    <reason>The reason was...</reason>
    <link rel="recipient" href="..." />
</shareFailure>

Schema

start = share

share= element h:share{
  link+,
  element h:message{xsd:string}
}
⚠️ **GitHub.com Fallback** ⚠️