WorkspaceNew - Huddle/huddle-apis GitHub Wiki

Summary

The Membership Workspaces API is a representation of a given Workspace within Huddle.

Table of contents

Operation
Retrieving a workspace
Retrieving user workspaces
Create a workspace
Create a workspace (Template)
Leave a workspace
Retrieving workspace managers
Add workspace managers
Remove workspace managers
Retrieve workspace users
Retrieve workspace user
Retrieving User Teams
Update Workspace User
Remove a user from a workspace
Bulk Invitations To Teams

Operations

Retrieve a Workspace

You can GET a given Workspace by its ID.

Example

Example request, asking for the Workspace with ID 123:

GET /workspaces/123 HTTP/1.1
Accept: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+json

{
  "links": [
    { "rel": "self", "href": "..." },
    { "rel": "parent", "href": "..." },
    { "rel": "leave", "href": "..." },
    { "rel": "teams", "href": "..." },
    { "rel": "managers", "href": "..." }
  ],
  "name": "My Important Workspace",
  "createdDate": "2014-07-04T14:13:57.447Z"
}

Response Properties

Name Description
name The name of the workspace
createdDate The date the workspace was created

Response Link relations

Name Description Methods
self The URI of this Workspace. GET
parent The URI of the Account the Workspace belongs to. GET
leave The URI to leave this Workspace. GET
teams The URI to request the list of Teams for the Workspace. GET
managers The URI to request the list of Managers for the Workspace. GET

Other Responses

Case Response
Invalid authorization token 401 Unauthorized
Actor is not an authorised user 403 Forbidden
Workspace does not exist 404 Not Found

Retrieve User Workspaces

Gets all workspaces the authorised user has access to.

Example

An example of a request to get all workspaces accessible to an authorised user.

Request

GET /workspaces HTTP/1.1
Accept: application/json
Authorization: Bearer frootymcnooty/vonbootycherooty

Request Properties

There is no request body and therefore no request properties for this API endpoint.

Response

HTTP/1.1 200 Ok
Content-Type: application/json

{
    "links": [
        {"rel" : "self", "href" : "..."},
        {"rel" : "parent", "href" : "..."}
    ],
    "workspaces": [
        {
            "links": [
                ...

            ],
            "name": "Workspace 1",
            "createdDate": "2019-12-11T00:00:00.000Z"
        },
        {
            "links": [
                ...

            ],
            "name": "Workspace 2",
            "createdDate": "2019-12-10T00:00:00.000Z"
        }
    ]
}

Response Properties

Name Description
workspaces Individual links to each workspace the authorised user has access to

Response Link relations

See Retrieving a workspace

Other Responses

Refer to General HTTP Status Codes.

Below are responses related to this resource

Case Response
Invalid authorization token 401 Unauthorized

Create a Workspace

Workspaces can be created by account managers - or any account member if the account is configured to allow anyone to create workspaces.

The workspace creator will be added as a workspace manager of the new workspace by default.

Example

Request

POST /accounts/456/workspaces HTTP/1.1
Content-Type: application/json
Authorization: Bearer frootymcnooty/vonbootycherooty

{
  "name": "My first workspace!",
  "description": "My first workspace description"
}

Response

HTTP/1.1 201 Created
Content-Type: application/vnd.huddle.data+json
Location: .../workspaces/12345

{
  "links": [
    { "rel": "self", "href": "..." },
    { "rel": "parent", "href": "..." },
    { "rel": "leave", "href": "..." },
    { "rel": "teams", "href": "..." },
    { "rel": "managers", "href": "..." }
  ],
  "name": "My first workspace!",
  "description": "My first workspace description",
  "createdDate": "2019-05-04T14:13:57.447Z"
}

Response Properties

Name Description
name The name of the workspace
description The description of the workspace
createdDate The date the workspace was created

Other Responses

Refer to General HTTP Status Codes.

Below are responses related to this resource

Case Response
Invalid authorization token 401 Unauthorized
Account does not exist 404 Not Found
Actor is not an authorised user 403 Forbidden

Create a Workspace Using Another Workspace As a Template

Request

POST /accounts/456/workspaces HTTP/1.1
Content-Type: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

{
  "name": "My first workspace!",
  "description": "My first workspace description",
  "template": {
    "sourceWorkspace": ".../workspaces/12345",
    "copyFolders": true,
    "copyDocuments": true,
    "copyTasks": true,
    "dueDateOfFirstTask": "2019-12-06",
    "copyTeams": true
  }
}
  • dueDateOfFirstTask accepts date according to ISO 8601 format.

Response

HTTP/1.1 201 Created
Content-Type: application/vnd.huddle.data+json
Location: .../workspaces/12346

{
  "links": [
    { "rel": "self", "href": "..." },
    { "rel": "parent", "href": "..." },
    { "rel": "leave", "href": "..." },
    { "rel": "teams", "href": "..." },
    { "rel": "managers", "href": "..." }
  ],
  "name": "My first workspace!",
  "createdDate": "2019-12-06T00:00:00.000Z"
}

Response Properties

Name Description
name The name of the workspace
description The description of the workspace
createdDate The date the workspace was created

Other Responses

Refer to General HTTP Status Codes.

Below are responses related to this resource

Case Response
Invalid authorization token 401 Unauthorized
Account does not exist 404 Not Found
Actor is not an authorised user 403 Forbidden

Leave a Workspace

Request

POST /workspaces/123/leave HTTP/1.1
Authorization: Bearer frootymcnooty/vonbootycherooty

Response

HTTP/1.1 202 Accepted

Other Responses

Refer to General HTTP Status Codes.

Below are responses related to this resource

Case Response
Invalid authorization token 401 Unauthorized
Workspace does not exist 404 Not Found

Retrieve Workspace managers

You can GET all workspace managers and the metadata of the managers in a workspace.

Example

Example request, asking for the Workspace managers from the Workspace with ID 123:

GET /workspaces/123/managers HTTP/1.1
Content-Type: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+json

{
  "links" : [
    { "rel" : "self", "href" : "..." },
    { "rel" : "parent", "href" : "..." },
    { "rel" : "add-managers", "href" : "..." },
    { "rel" : "remove-managers", "href" : "..." },
    { "rel" : "first", "href" : "..." },
    { "rel" : "previous", "href" : "..." },
    { "rel" : "next", "href" : "..." }
  ],
  "managers" : [
    {
      "name" : "Peter Parker",
      "email" : "[email protected]",
      "links" : [
            { "rel" : "self", "href" : "..." },
            { "rel" : "avatar", "href" : "..." },
            { "rel" : "alternate", "href": "..." }
      ]
    },
    ...
  ]
}

Response Properties

Name Description
managers The list of managers for the given workspace

Response Link relations

Property Name Description Methods
self The URI of the workspace managers collection. GET
parent The URI of the Workspace that the managers belongs to. GET
add-managers The URI to add managers to the Workspace. POST
remove-managers The URI to remove managers from the Workspace. POST
first The URI of the first page of managers. GET
previous The URI of the previous page of managers. GET
next The URI of the next page of managers. GET
managers self The URI of the user GET
managers avatar The URI of the user's avatar GET
managers alternate The URI of the user's profile GET

Other Responses

Case Response
Invalid authorization token 401 Unauthorized
Actor is not an authorised user 403 Forbidden
Workspace does not exist 404 Not Found

Filters

Query string parameters are used to filter the managers in a workspace. Returns empty list of managers if no managers were found that match your query.

Request:

GET /workpaces/123/managers?q=jon&pagesize=20&skip=0 HTTP/1.1
Accept: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty
Parameter Default value Additional notes
q Match a workspace manager on firstname, lastname, email
pagesize 20
skip 0

Response shape is the same as in Retrieve Workspace Managers

Add Workspace Managers

You can add managers to a workspace.

Example

Example request to add workspace managers for the Workspace with ID 123:

POST /workspaces/123/managers/add HTTP/1.1
Content-Type: application/json
Authorization: Bearer frootymcnooty/vonbootycherooty

{
  "links" : [
    { "rel" : "manager", "href" : "..." },
    ...
  ]
}

Example response:

If successful, this method will return with a 200 OK status code. The response body will be the updated Workspace Manager collection. This response uses the standard error codes and returns standard response headers.

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+json
Content-Location: /workspaces/123/managers

{
  "links" : [
    { "rel" : "self", "href" : "..." },
    { "rel" : "parent", "href" : "..." },
    { "rel" : "add-managers", "href" : "..." },
    { "rel" : "remove-managers", "href" : "..." },
    { "rel" : "first", "href" : "..." },
    { "rel" : "previous", "href" : "..." },
    { "rel" : "next", "href" : "..." }
  ],
  "managers" : [
    {
      "name" : "Peter Parker",
      "email" : "[email protected]",
      "links" : [
            { "rel" : "self", "href" : "..." },
            { "rel" : "avatar", "href" : "..." },
            { "rel" : "alternate", "href": "..." }
      ]
    },
    ...
  ]
}

Response Properties

Name Description
rel The relationship of the resource for the given context
href The URI of the specified resource

Other Responses

Case Response
Invalid authorization token 401 Unauthorized
Actor is not an authorised user 403 Forbidden
Workspace does not exist 404 Not Found
User/s manager/s does not exist 404 Not Found

Remove Workspace Managers

You can remove managers from a workspace.

Example

Example request for removing workspace managers from the workspace with ID 123:

POST /workspaces/123/managers/remove HTTP/1.1
Content-Type: application/json
Authorization: Bearer frootymcnooty/vonbootycherooty

{
  "links" : [
    { "rel" : "manager", "href" : "..." },
    ...
  ]
}

Example response:

If successful, this method will return with a 200 OK status code. The response body will be the updated Workspace Manager collection. This response uses the standard error codes and returns standard response headers.

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+json
Content-Location: /workspaces/123/managers

{
  "links" : [
    { "rel" : "self", "href" : "..." },
    { "rel" : "parent", "href" : "..." },
    { "rel" : "add-managers", "href" : "..." },
    { "rel" : "remove-managers", "href" : "..." },
    { "rel" : "first", "href" : "..." },
    { "rel" : "previous", "href" : "..." },
    { "rel" : "next", "href" : "..." }
  ],
  "managers" : [
    {
      "name" : "Joseph Alligator",
      "email" : "[email protected]",
      "links" : [
            { "rel" : "self", "href" : "..." },
            { "rel" : "avatar", "href" : "..." },
            { "rel": "alternate", "href": "..." }
      ]
    },
    ...
  ]
}

Response Properties

Name Description
rel The relationship of the resource for the given context
href The URI of the specified resource

Other Responses

Case Response
Invalid authorization token 401 Unauthorized
Actor is not an authorised user 403 Forbidden
Workspace does not exist 404 Not Found
User/s manager/s does not exist 404 Not Found

Retrieve Workspace users

You can GET all workspace users and their associated metadata.

Example

Example request, asking for the Workspace users from the Workspace with ID 123:

GET /workspaces/123/users HTTP/1.1
Content-Type: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+json

{
  "users" : [
    {
      "name" : "Peter Parker",
      "email" : "[email protected]",
      "lastLogin" : "2020-03-03T00:00:00.000Z",
      "workspaceManager" : true,
      "teamsPreview": [
        {
          "name": "team1",
          "links": [{"rel": "self", "href": "..."}]
        },
      ],
      "links" : [
        { "rel" : "self", "href" : "..." },
        { "rel" : "user", "href" : "..." },
        { "rel" : "avatar", "href" : "..." },
        { "rel" : "alternate", "href": "..." },
        { "rel" : "update", "href": "..." },
        { "rel" : "teams", "href" : "...", "count": "..." },
        { "rel" : "remove-from-workspace", "href": "..." },
        { "rel" : "remove-from-account", "href": "..." }
      ]
    },
  ],
  "links" : [
    { "rel" : "self", "href" : "..." },
    { "rel" : "parent", "href" : "..." },
    { "rel" : "first", "href" : "..." },
    { "rel" : "previous", "href" : "..." },
    { "rel" : "next", "href" : "..." }
  ]
}

Response Properties

Name Description
users The list of users in the given workspace

Response Link relations

Property Name Description Methods
self The URI of the workspace users collection. GET
parent The URI of the Workspace that the users belong to. GET
first The URI of the first page of users. GET
previous The URI of the previous page of users. GET
next The URI of the next page of users. GET
users self The URI of the workspace user GET
users user The URI of the user GET
users avatar The URI of the user's avatar GET
users alternate The URI of the user's profile GET
users teams The number of teams a user belongs to GET
users update The URI to update workspace user POST
users remove-from-workspace The URI to remove the user from this workspace DELETE
users remove-from-account The URI to remove the user from this account DELETE

Other Responses

Case Response
Invalid authorization token 401 Unauthorized
Actor is not an authorised user 403 Forbidden
Workspace does not exist 404 Not Found

Filters

Query string parameters are used to filter the users in a workspace. Returns empty list of users if no users were found that match your query.

Request:

GET /workpaces/123/users?q=jon&pagesize=20&skip=0&isWorkspaceManager=true HTTP/1.1
Accept: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty
Parameter Default value Additional notes
q Match a workspace user on firstname, lastname, email
isWorkspaceManager false Match a user if they are also a Workspace Manager
pagesize 20
skip 0

Response shape is the same as in Retrieve Workspace Users

Retrieve Workspace user

GET /workspaces/123/users/999 HTTP/1.1
Accept: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

HTTP/1.1 200 OK
Content-Type: application/json

{
  "links": [
        { "rel" : "self", "href" : "..." },
        { "rel" : "user", "href" : "..." },
        { "rel" : "avatar", "href" : "..." },
        { "rel" : "alternate", "href": "..." },
        { "rel" : "update", "href" : "..." },
        { "rel" : "teams", "href" : "...", "count": "..." },
        { "rel" : "remove-from-workspace", "href": "..." },
        { "rel" : "remove-from-account", "href": "..." }
    ],
  "name": "Peter Parker",
  "email": "[email protected]",
  "lastLogin": "2020-03-03T00:00:00.000Z",
  "workspaceManager": true,
  "teamsPreview": [
      {
          "name": "team1",
          "links": [
              { "rel": "self", "href": "..." }
          ]
      }
  ]
}

Response Link relations

Property Name Description Methods
self The URI of the workspace user GET
user The URI of the user GET
avatar The URI of the user's avatar GET
alternate The URI of the user's profile GET
update The URI to update workspace user POST
teams The number of teams a user belongs to GET
remove-from-workspace The URI to remove the user from this workspace DELETE
remove-from-account The URI to remove the user from this account DELETE

Retrieving User Teams

Retrieves a collection of Teams that the User belongs to.

Request

Retrive a list of Teams for User Id 456 belongs to in Workspace 123.

GET /workspaces/123/users/456/teams HTTP/1.1
Accept: application/json
Authorization: Bearer frootymcnooty/vonbootycherooty

Request Filters

Filters are query string parameters that are used to filter the list of teams returned, e.g.

GET /workspaces/123/users/456/teams?pagesize=20&skip=0
Parameter Default value Additional Notes
pagesize 20 The maximum number of elements to return, between 1 - 100.
skip 0 The number of results to skip

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+json

{
    "teams": [
        {
            "links": [
                { "rel" : "self", "href": "/workspaces/123/teams/12" },
                { "rel" : "parent", "href" : "/workspaces/123" },
                etc...
            ],
            "name": "My Team 1",
            "description": "Description of My Team 1"
        },
        ...
    ],
    "links": [
        { "rel" : "self", "href": /workspaces/123/users/456/teams" },
        { "rel" : "parent", "href": "/workspaces/123/users/456" },
        { "rel" : "first", "href" : "..." },
        { "rel" : "previous", "href" : "..." },
        { "rel" : "next", "href" : "..." }
    ]
}

Response Properties

Name Description
teams The collection of Team resources

Response Link Relations

Name Description Methods
self The URI of this User Teams resource GET
parent The URI of the User resource GET

Other Responses

Name Response
Invalid authorization token 401 Unauthorized
Insufficient permissions to view User 403 Forbidden
User does not exist 404 Not Found

Update Workspace user

If you have permission, you can update a workspace user's workspace manager role and which teams they belong to.

Example

Example request to update the Workspace user. The updates are to; remove them as a workspace manager, add them to a new team and remove them from a team.

POST /workspaces/123/users/999 HTTP/1.1
Content-Type: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

{
  "workspaceManager" : false,
  "addToTeams" : [
    {"rel" : "team", "href" : ".../teams/10"}
  ],
  "removeFromTeams" : [
    {"rel" : "team", "href" : ".../teams/11"}
  ]
}

Response:

HTTP/1.1 200 OK
Content-Type: application/json

The response shape and details match Retrieve Workspace Users, except for in the case of partial success.

Other Responses

Name Response
Operation succeeded, and user is no longer a member of the workspace as a result 204 No Content
Malformed request 400 Bad Request
Invalid authorization token 401 Unauthorized
Insufficient permissions to update user 403 Forbidden
Workspace, user or team does not exist 404 Not Found

NB: In the case of an error code, partial success is possible when using this endpoint. That is, some changes may have been successfully applied.

Remove a user from a workspace

You can get the required URL from Retrieve workspace users response link for remove-from-workspace

Example

Example request, asking to remove a user from a workspace:

DELETE /workspaces/123/users/456 HTTP/1.1
Authorization: Bearer frootymcnooty/vonbootycherooty

Example response:

HTTP/1.1 204 No Content

Other Responses

Case Response
Invalid authorization token 401 Unauthorized
Actor is not an authorised user 403 Forbidden
Workspace or User does not exist 404 Not Found