We’re making some changes to the way you use memberships API. As part of this
change we’ll be retiring a number of endpoints, and adding new endpoints.
The /memberships endpoint is now available for everyone. The old endpoints
will remain available until the end of the opt-out period.
Membership-capable resource: Asana objects that have API resources that
support user membership:
Goals
Portfolios
Projects
Teams
Workspaces
Current Behavior
Memberships for various entities have specific sets of endpoints and
resources to represent these memberships
Only users can have memberships
All members of membership-capable resources have the same access level as
the membership-capable resource
New Behavior
Users have a standard_access_level for Projects, Portfolio, and Goals via
their direct membership.
However, users may be on a team that has a different standard_access_level
than their direct membership. When there is a difference, the highest access
level across all memberships (if a user is on several teams with access),
becomes the effective_access_level. This effective_access_level is then used
to determine the user’s tier of access.
One set of endpoints will be responsible for management all memberships
The new Memberships resource will define the Asana resource for
membership (e.g., Project, Team, Goal, etc)
Memberships can now include teams, such that you can add or remove an entire
team from an Asana resource that supports membership
Access-levels for members of membership-capable resources are determined by
their highest party membership, and this is called effective_access_level.
E.g., when a member has access to a membership-capable resource for
multiple reasons, such as through direct membership or through a team
that has membership, the highest access level of these associations is
used to determine their access to the resource.
Important: The effective_access_level field of the Memberships
resource won’t be available until a separate changeset. But, the access
level will impact requests when this changeset becomes available for
Opt-In.
Prototype of the new Membership resource (when a member can be a team or a
user):
Thank you for the update. Couple questions about the direction this is going:
Will the new API endpoints support changing owners to a membership-capable resource? Specifically, for Portfolios, there’s currently no way to assign an Owner via the API. Can there be a “role” parameter added to the Membership resource for this purpose?
Reason I’m thinking “Roles” for Portfolios is because it would align well with “Roles” in Project Memberships. In the Overview page of a Project, the “Project Owner” role can be assigned with the projects endpoint but the same cannot be said about the portfolios endpoint. Seems like an additional “role” parameter to the Membership resource would do the trick?
Users have a standard_access_level for Projects, Portfolio, and Goals via
their direct membership. At the moment in the API, we’ve exposed this standard_access_level as write_access and other properties – this is part of what will also be changing once we update the docs and schema.
However, users may be on a team that has a different standard_access_level
than their direct membership. When there is a difference, the highest access
level across all memberships (if a user is on several teams with access),
becomes the effective_access_level. This effective_access_level is then used
to determine the user’s tier of access.
That said, we actually have modified the spec for this feature for the first
iteration to remove the GET /memberships/effective_access_level/* routes. We
expect to add it back the feature as a property on membership objects instead of its own
endpoint to improve the ergonomics for API users.
I’ll update the original post with these details and your first comment!
If the user is already a member of that sources, it would be the PUT form. If the user is not a member, you’d use the POST form and then be issued a membership gid in the response.
And yes, until this becomes available as opt-in, you won’t be able to test it. I will comment on this thread once it becomes available (which we’re anticipating is tomorrow).
When the resource is a team, can it have a team as a member? (If yes, then can that be the same team as the resource? I would assume no.)
In the first prototype you show where the resource can contain users or teams, how does one know whether a given member is a user or a team?
To make sure I’m clear: standard_access_level will be returned, and can be set, when this changeset is in effect. However, effective_access_level will not initially be available to get or set.
If I’m right on #3, then this would seem to mean that while one will receive a standard_access_level for a member, it might not be the access level that’s actually in effect for that member (if they have a higher effective_access_level that we won’t be able to see). Similarly, one can set standard_access_level, as in your example of setting a comment-only user, but that action might not actually have any effect if the user has an effective_access_level that’s higher than the one that’s being attempted to be set (and after making the call to set the standard_access_level, we’ll have no way of knowing whether it actually worked or not).
This was confusing in the OP, and I’ll update to include this! Thanks for the keen eye and great question!
Correct, as of now, the following are true:
only standard_access_level is available
effective_access_level is not available
it’s possible that the “effective access level” (which will be available in the future as effective_access_level) that’s in effect for a member may be greater than their standard_access_level
it is not possible to identify the above state via the API.
In the future, once effective_access_level becomes available, that state will be identifiable.
Hi @sasha_f , thanks for the updates—excited to test-drive it this week!
One question, and sorry if I’ve missed this context somewhere further up in this thread. Is there a way to explicitly turn off notifications via these new endpoints? Eg, in this screenshot I would assume the standard_access_level options you outlined (below) map to the Can edit and Can comment options in the GUI.
Do those values somehow also map to notification preferences (the second highlighted bit in that GUI screenshot)? Or is there another way to set/disable notifications via this endpoint?
Okay, thanks for checking! Also, when trying to create a new Project Membership, I’m getting:
"message": "Please include a valid standard_access_level: ADMIN CONTRIBUTOR COMMENTER",
Tried sending both the documentedwrite_all and the prompted CONTRIBUTOR values in upper/lower case. Do we (can we, if so?) need to opt in to this API update, to have access to these endpoints? That endpoint does work when we remove the standard_access_level altogether.
Also getting this, when attempting to hit the DELETE endpoint for memberships: