RFCs are a way for Atlassian to share what we’re working on with our valued developer community.
It’s a document for building shared understanding of a topic. It expresses a technical solution, but can also communicate how it should be built or even document standards. The most important aspect of an RFC is that a written specification facilitates feedback and drives consensus. It is not a tool for approving or committing to ideas, but more so a collaborative practice to shape an idea and to find serious flaws early.
Please respect our community guidelines: keep it welcoming and safe by commenting on the idea not the people (especially the author); keep it tidy by keeping on topic; empower the community by keeping comments constructive. Thanks!
Project Summary
We’re introducing Jira Cloud REST API endpoints for Plans to allow Jira admins to programmatically manage plan configurations and their team configurations.
- Publish: 18 December 2024
- Discuss : 3 February 2025
- Resolve : 3 March 2025
Problem
The Jira Cloud REST API currently doesn’t provide any endpoints for Plans. As a result, organizations face the following challenges:
- High manual effort: As organizations grow, plan management becomes burdensome, particularly due to its current manual nature without any automation. Handling different facets of plans, such as their creation, updates, and configurations, is labor-intensive and susceptible to mistakes. This issue is exacerbated in large organizations that experience frequent changes.
- Lack of automation: Without an API, project managers and admins can’t automate repetitive tasks related to plan management. This lack of automation leads to inefficiencies, affects their productivity, and increases their workload.
- Scalability: As organizations grow, the complexity and volume of their plans increase. Managing this data at scale without an API can be cumbersome and hinder the scalability of their project management processes.
Proposed Solution
We’re introducing the following Jira Cloud REST API endpoints for Plans to allow Jira admins to programmatically manage plan configurations and their team configurations:
- Plans:
- Get plans paginated:
GET /rest/api/{2|3|latest}/plans/plan→ link - Create plan:
POST /rest/api/{2|3|latest}/plans/plan→ link - Duplicate plan:
POST /rest/api/{2|3|latest}/plans/plan/{planId}/duplicate→ link - Get plan:
GET /rest/api/{2|3|latest}/plans/plan/{planId}→ link - Update plan:
PUT /rest/api/{2|3|latest}/plans/plan/{planId}→ link - Trash plan:
PUT /rest/api/{2|3|latest}/plans/plan/{planId}/trash→ link - Archive plan:
PUT /rest/api/{2|3|latest}/plans/plan/{planId}/archive→ link
- Get plans paginated:
- Teams in plan:
- Get teams in plan paginated:
GET /rest/api/{2|3|latest}/plans/plan/{planId}/team→ link - Create plan-only team:
POST /rest/api/{2|3|latest}/plans/plan/{planId}/team/planonly→ link - Add Atlassian team to plan:
POST /rest/api/{2|3|latest}/plans/plan/{planId}/team/atlassian→ link - Get plan-only team:
GET /rest/api/{2|3|latest}/plans/plan/{planId}/team/planonly/{planOnlyTeamId}→ link - Get Atlassian team in plan:
GET /rest/api/{2|3|latest}/plans/plan/{planId}/team/atlassian/{atlassianTeamId}→ link - Update plan-only team:
PUT /rest/api/{2|3|latest}/plans/plan/{planId}/team/planonly/{planOnlyTeamId}→ link - Update Atlassian team in plan:
PUT /rest/api/{2|3|latest}/plans/plan/{planId}/team/atlassian/{atlassianTeamId}→ link - Delete plan-only team:
DELETE /rest/api/{2|3|latest}/plans/plan/{planId}/team/planonly/{planOnlyTeamId}→ link - Remove Atlassian team from plan:
DELETE /rest/api/{2|3|latest}/plans/plan/{planId}/team/atlassian/{atlassianTeamId}→ link
- Get teams in plan paginated:
Design Principles
We’ve designed the endpoints with the following principles in mind:
- Only Plans entities: The endpoints only support CRUD operations for Plans entities, which makes them easy to use and performant and avoids overlap with existing Jira Cloud REST API endpoints. For example, the Get plan endpoint returns issue sources but not projects, filters, boards, or their issues.
- Non-Plans entity references by ID: For the same reasons, the endpoints only reference non-Plans entities by ID. For example, the Create plan and Update plan endpoints accept a project ID, filter ID, or board ID to create an issue source.
- JSON Patch: The Update plan, Update plan-only team, and Update Atlassian team in plan endpoints use JSON Patch to prevent accidentally deleting data and allow fine-grained modifications, which mitigates the coarse-grained nature of the Update plan endpoint. There is one caveat: add operations don’t adhere to array indexes in target locations to eliminate the need to delete and recreate data, which would result in additional database load. Call the Get plan, Get plan-only team, and Get Atlassian team in plan endpoints to find out the order of array elements.
- No scenarios: The endpoints ignore scenarios and immediately save all changes, which makes them easy to use and performant and eliminates the need to introduce an additional endpoint that must be called after each call to the Update plan, Create plan-only team, Add Atlassian team to plan, Update plan-only team, and Update Atlassian team in plan endpoints.
- Consistency with Plans: The endpoints are consistent with the Plans UI: they use the same names and do the same validation checks. For example, like the Plans UI, the Create plan and Update plan endpoints check that names aren’t longer than 255 characters.
- Consistency with the Jira Cloud REST API: From a technical perspective, the endpoints are consistent with the existing Jira Cloud REST API endpoints. For example, the Update plan, Update plan-only team, and Update Atlassian team in plan endpoints require PUT instead of PATCH as HTTP request method.
Further Changes
We currently don’t plan to make any further changes, but we’ll consider refining the endpoints or adding new ones.
Asks
While we would appreciate any reactions you have to this RFC, we’re especially interested in learning more about:
- Do you see any challenges that the endpoints fail to address?
- Do you have any concerns about the endpoints?
- How would you like us to refine the endpoints, and why?
- Would you like us to make any other changes to the endpoints, and why?
- Would you like us to introduce any other endpoints, and why?