tl;dr:
- no immediate action is required unless you use goal membership endpoints:
- known as “Team-Sharing” in UI
- re-launch of [PAUSED] Upcoming changes that impact getting and setting
memberships and access levels - incrementally adding functionality to include a “Team” as a member of a
resource- starting with Goals
- future action will be required as we include other Work Graph resources in
this migration (Projects, Portfolios, Workspaces, etc) - all membership endpoints are being incrementally moved over to one new
endpoint:/memberships- each Work Graph resource will have its own small deprecation period
/membershipswill support all Work Graph resources from the beginning
Hey folks,
We’re relaunching a more focused change to how the API enables you to manipulate members of Work Graph resources.
In the Asana UI, you can now add a Team as a member of goals:
This is known as “Team-Sharing”. Over time, we will roll out the same functionality to other Work Graph resources, such as Projects, Portfolios, and Workspaces.
There will be an independent migration period for each Work Graph resource as it moves over to the Team-Sharing.
Here’s what the Goal Team-Sharing migration looks like:
| Old Endpoints | New Endpoints | |
|---|---|---|
POST /goals/:goal_gid/addFollowers |
→ | POST /memberships |
POST /goals/:goal_gid/removeFollowers |
→ | DELETE /memberships |
| (previously unavailable functionality) | → | GET /memberships |
Goal Team-Sharing Migration Timeline
- 2023-03-22: the migration period starts:
Asana-Change: name=new_goal_memberships;affected=trueheader will
begin appearing for API clients of old Goal membership endpoints:- those API clients should begin migrating their calls to the new
/membershipsendpoint
- 2023-04-19: the migration period ends:
- API clients of the old Goal membership endpoints must be using the
/membershipsendpoint: - calls to the old Goal membership endpoints will fail with a
404 - the
/membershipsendpoint will be available as a replacement
- API clients of the old Goal membership endpoints must be using the
We will follow a similar migration timeline for the other Work Graph resources,
as they begin migrating.
/memberships endpoint
Request
GET /api/1.0/memberships?parent=123456
Response
HTTP/1.1 200 OK
Asana-Change: name=new_memberships;affected=true
{
"data": [
{
"goal": {
"gid": "123456",
"name": "Team-Sharing API Demo",
"owner": {
"gid": "987643",
"name": "Sasha F",
"resource_type": "user"
},
"resource_type": "goal"
},
"is_commenter": false,
"is_editor": true,
"member": {
"gid": "4678",
"name": "Sasha F",
"resource_type": "user"
},
"resource_type": "goal_membership"
}
]
}
FAQ
Will Teams support Teams as members
No. Only users can be added as members for Teams. Teams will not be recursive.
If I don’t use Goal memberships, do I currently have to do anything?
No, you don’t need to do anything yet. If you use any other memberships, you
will eventually need to migrate to the /memberships endpoint.
What happened to Standard Access Levels (standard_access_level) from the
original announcement?
Standard Access Levels are being deferred for two reasons:
- Standard Access Levels are only currently available for some Work Graph
resources - Adding Team-Sharing and Standard Access Levels significantly complicates
this change for developers and makes this harder, especially as both
Team-Sharing and Standard Access Levels are being incrementally rolled
out, one Work Graph resource at a time.
Timeline
| Date | Event |
|---|---|
| 2022-10-21 | Original announcement |
| 2023-01-19 | Timeline adjustment |
| 2023-01-25 | Spec adjustment[1] |
| 2023-03-23 | Opt-In available |
| 2023-04-27 | Goal follower endpoints no longer available |
Yours in Developer Relations,
Sasha, on behalf of the Asana API Team
added clarifying text about
effective_access_leveland removed
GET /memberships/effective_access_level/parent. ↩︎