TeamsNew

Summary

The Membership Team API is a representation of a given Team within Huddle.

Beta warning

The Membership Team API is in Alpha

Status

Operation	Status
List of Teams in Workspace	Alpha
Retrieve a Team	Alpha
Create a Team	Alpha
Update a Team	Alpha
Delete a Team	Alpha
Add Members to a Team	Alpha
Retrieve Team Members	Alpha
Remove Members from a Team	Alpha

Operations

List of Teams in Workspace

Example

The following example requests teams for workspace with id 123.

Request:

GET /workspaces/123/teams HTTP/1.1
Accept: application/vnd.huddle.data+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/teams?name=my&hasUser=123&pagesize=20&skip=0

Parameter	Default value	Additional Notes
name		Searches for team names within a workspace which begin with the name query string.
hasUser		Checks wether or not a given user belongs to a team or not, indicated by the optional property userIsMember.
pagesize	20	The maximum number of elements to return, between 1 - 100.
skip	0	The number of elements to skip.

Response:

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

{
  "links" : [
    { "rel" : "self", "href" : "..." },
    { "rel" : "parent", "href" : "..." },
    { "rel" : "create-team", "href": "..." },
    { "rel" : "bulk-invitation", "href": "..." }
    { "rel" : "first", "href" : "..." },
    { "rel" : "previous", "href" : "..." },
    { "rel" : "next", "href" : "..." },
  ],
  "teams": [
        {
            "links": [
                { "rel" : "self", "href": "..." },
                { "rel" : "parent", "href" : "..." },
                { "rel" : "add-member", "href" : "..." },
                { "rel" : "update", "href" : "..." },
                { "rel" : "delete", "href" : "..." },
                { "rel" : "remove", "href" : "..." }
            ],
            "name": "My Team 1",
            "description": "Description of My Team 1",
            "userIsMember": true, // optional property, will appear query param hasUser is passed
            
        },
        {
            "links": [
                { "rel" : "self", "href": "..." },
                { "rel" : "parent", "href" : "..." },
                ...
            ],
            "name": "My Team 2",
            "description": "Description of My Team 2",
            "userIsMember": false
        }
    ]
}

Response Properties

Name	Description
teams	The list of the teams for the workspace

Response Link relations

Property	Name	Description	Methods
	self	The URI of this collection of teams	GET
	parent	The URI of the workspace the teams collection belongs to	GET
	create-team	If you have permission, the URI to create a new Team	POST
	bulk-invitation	If you have permission, the URI to bulk invite people to Teams	POST
	first	The URI of the first page of teams.	GET
	previous	The URI of the previous page of teams.	GET
	next	The URI of the next page of teams.	GET
teams	parent	The URI of the workspace the team belongs to	GET
teams	self	The URI of the team	GET
teams	add-member	The URI to add members to a team	POST
teams	update	The URI to update team details	PATCH
teams	delete	The URI to delete the team	DELETE
teams	remove-members	The URI to remove members from a team	POST

Other Responses

Case	Response
Invalid authorization token	401 Unauthorized
Insufficient permissions to get teams	403 Forbidden
Workspace does not exist	404 Not Found

Retrieve a Team

You can GET a given team and it will display the information for that team.

Example

The following example requests information for a team with ID 456 within a workspace with id 123.

Request:

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

Response:

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

{
  "links" : [
    { "rel" : "self", "href" : "..." },
    { "rel" : "parent", "href" : "..." },
    { "rel" : "members", "href" : "...", "count": 3 },
    { "rel" : "add-member", "href" : "..." },
    { "rel" : "update", "href": "..." },
    { "rel" : "delete", "href": "..." }
  ],
  "name" : "My Important team",
  "description" : "My team description"
}

Response Properties

Name	Description
name	The name of the team

Response Link relations

Name	Description	Methods
self	The URI of this team	GET
parent	The URI of the workspace the team belongs to	GET
members	The URI of the members that belongs to this team	GET
add-member	If you have permission, the URI to add user to Team	POST

Other Responses

Case	Response
Invalid authorization token	401 Unauthorized
Actor has insufficient permissions	403 Forbidden
Team or Workspace does not exist	404 Not Found

Create a Team

Example

The following example requests a team to be created for a workspace with id 123. A workspace cannot contain duplicate team names.

Request:

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

{
    "name": "My first team!",
    "description": "Description of my first team!"
}

Response:

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

{
  "links" : [
    { "rel" : "self", "href" : "..." },
    { "rel" : "parent", "href" : "..." },
    { "rel" : "add-member", "href" : "..." }

  ],
  "name" : "My first team!",
  "description": "Description of my first team!"
}

Request Properties

Name	Description
name	The name of the team

Other Responses

Refer to General HTTP Status Codes.

Below are responses related to this resource:

Case	Response
Actor has insufficient permissions	403 Forbidden
Workspace does not exist	404 Not Found
Name already exists	409 Conflict

Update a Team

You can UPDATE the name and description of a team.

Example

Request:

PATCH /workspaces/123/teams/456 HTTP/1.1
Content-Type: application/json
Authorization: Bearer frootymcnooty/vonbootycherooty

{
  "name": "New name for Team 1",
  "description": "New description of Team 1"
}

Response:

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

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

{
  "links" : [
    { "rel" : "self", "href" : "..." },
    { "rel" : "parent", "href" : "..." },
    ...
  ],
  "name": "New name for Team 1",
  "description": "New description of Team 1"
}

Request Properties

Name	Description
Name	Team Name
Description	Team Description

Other Responses

Refer to General HTTP Status Codes. Below are responses related to this resource:

Case	Response
Invalid authorization token	401 Unauthorized
Actor has insufficient permission	403 Forbidden
Actor is not a member of the workspace	403 Forbidden
New Team name matches and existing team name	409 Conflict

Delete a Team

You can DELETE a given team that has no Team Members associated with it.

Example

Request:

DELETE /workspaces/123/team/456
Authorization: Bearer frootymcnooty/vonbootycherooty

Response:

HTTP/1.1 204 No Content

Other Responses

Refer to General HTTP Status Codes. Below are responses related to this resource:

Case	Response
Invalid authorization token	401 Unauthorized
Actor has insufficient permission	403 Forbidden
Workspace does not exist	404 Not Found
Team has one or more members	409 Conflict

Add Members to a Team

You can POST users (only their self link needs to be included) to add them as team members

Example

The following example adds a user to the team with ID 456

Request:

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

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

Response:

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+json
Link: /workspaces/123/teams/456
{
  "links" : [
    { "rel" : "self", "href" : "..." },
    { "rel" : "parent", "href" : "..." },
    { "rel" : "add-member", "href" : "..." },
    { "rel" : "remove-members", "href" : "..." }, 
    { "rel" : "first", "href" : "..." },
    { "rel" : "next", "href" : "..." },
    { "rel" : "previous", "href" : "..." }
  ],
  "members" : [
    {
        "name" : "Serious Sam",
        "email" : "[email protected]",
        "links" : [
            { "rel" : "self", "href" : "..." },
            { "rel" : "avatar", "href" : "..." },
            { "rel": "alternate", "href": "..." }
        ]
    },
    ...
  ]
}

Request Properties

Name	Description
links	An array containing the "self" link of the user to add

Other Responses

Refer to General HTTP Status Codes. Below are responses related to this resource:

Case	Response
Actor has insufficient permission	403 Forbidden
Email address is not on allow list	400 Bad Request
Team does not exist	404 Not Found
Users not provided or invalid	400 Bad Request

Retrieve Team Members

You can GET all team members and the metadata of the members in a team.

Example

The following example requests information for members of a team with id 456 within a workspace with id 123.

Request:

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

Response:

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

{
  "links" : [
    { "rel" : "self", "href" : "..." },
    { "rel" : "parent", "href" : "..." },
    { "rel" : "add-member", "href" : "..." },
    { "rel" : "first", "href" : "..." },
    { "rel" : "next", "href" : "..." },
    { "rel" : "previous", "href" : "..." }
  ],
  "members" : [
    {
        "name" : "Serious Sam",
        "email" : "[email protected]",
        "links" : [
            { "rel" : "self", "href" : "..." },
            { "rel" : "avatar", "href" : "..." },
            { "rel": "alternate", "href": "..." }
        ]
    },
    ...
  ]
}

Filters

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

Request:

GET /workspaces/123/teams/456/members?q=ser&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 team member on firstname, lastname, email
pagesize	20
skip	0

Response shape is the same as in Retrieve Team Members

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

{
  "links" : [
    { "rel" : "self", "href" : "..." },
    { "rel" : "parent", "href" : "..." },
    { "rel" : "add-member", "href" : "..." },
    { "rel" : "first", "href" : "..." },
    { "rel" : "next", "href" : "..." },
    { "rel" : "previous", "href" : "..." }
  ],
  "members" : [
    {
        "name" : "Serious Sam",
        "email" : "[email protected]",
        "links" : [
            { "rel" : "self", "href" : "..." },
            { "rel" : "avatar", "href" : "..." },
            { "rel": "alternate", "href": "..." }
        ]
    },
    ...
  ]
}

Response Properties

Name	Description
members	The list of team members

Response Link relations

Property	Name	Description	Methods
	self	The URI of these members	GET
	parent	The URI of the team the members belong to	GET
	add-member	If you have permission, the URI to add user to Team	POST
	first	The URI to move to the first page	GET
	next	The URI to move to the next page	GET
	previous	The URI to move to the previous page	GET
members	self	The URI of the user	GET
members	avatar	The URI of the user's avatar	GET
members	alternate	The URI of the user's profile	GET

Other Responses

Case	Response
Invalid authorization token	401 Unauthorized
Actor has insufficient permissions	403 Forbidden
Team or Workspace does not exist	404 Not Found

Remove Members from a Team

Only Workspace Managers have the permissions to remove members from a team (including themselves).

Example

The following example removes a member from a team. The team ID in this example is 456.

Request:

POST /workspaces/123/teams/456/members/remove HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer frootymcnooty/vonbootycherooty

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

Response:

HTTP/1.1 200 OK
Content-Location: /workspaces/123/teams/456/members
Content-Type: application/json

{
  "links" : [
    { "rel" : "self", "href" : "..." },
    { "rel" : "parent", "href" : "..." },
    { "rel" : "add-member", "href" : "..." },
    { "rel" : "remove-members", "href" : "..." },
    { "rel" : "first", "href" : "..." },
    { "rel" : "next", "href" : "..." },
    { "rel" : "previous", "href" : "..." }
  ],
  "members" : [
    {
        "name" : "Serious Sam",
        "email" : "[email protected]",
        "links" : [
            { "rel" : "self", "href" : "..." },
            { "rel" : "avatar", "href" : "..." },
            { "rel": "alternate", "href": "..." }
        ]
    }
  ]
}

Request Properties

Name	Description
links	An array containing the "self" links of the members to remove

Other Responses

Refer to General HTTP Status Codes. Below are responses related to this resource:

Case	Response
Actor has insufficient permission	403 Forbidden
Team does not exist	404 Not Found