WorkspaceNew

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