Skip to content

feat(API): Add create comparison endpoint for branches [SCD-549] #966

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
theSoenke merged 4 commits into from
Dec 11, 2025
Merged

feat(API): Add create comparison endpoint for branches [SCD-549] #966

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
5ba36a1
feat(API): Add create comparison endpoint for branches [SCD-549]
bikmazefe Nov 13, 2025
11357b9
Drop 200 response
bikmazefe Nov 20, 2025
22058c1
Use more consistent operationId
bikmazefe Nov 28, 2025
e58d14f
Drop beta word
bikmazefe Dec 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
103 changes: 102 additions & 1 deletion doc/compiled.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5021,6 +5021,20 @@
}
}
},
"202": {
"description": "Accepted",
"headers": {
"X-Rate-Limit-Limit": {
"$ref": "#/components/headers/X-Rate-Limit-Limit"
},
"X-Rate-Limit-Remaining": {
"$ref": "#/components/headers/X-Rate-Limit-Remaining"
},
"X-Rate-Limit-Reset": {
"$ref": "#/components/headers/X-Rate-Limit-Reset"
}
}
},
"204": {
"description": "The resource was deleted successfully.",
"headers": {
Expand Down Expand Up @@ -5080,6 +5094,20 @@
}
}
},
"409": {
"description": "Conflict",
"headers": {
"X-Rate-Limit-Limit": {
"$ref": "#/components/headers/X-Rate-Limit-Limit"
},
"X-Rate-Limit-Remaining": {
"$ref": "#/components/headers/X-Rate-Limit-Remaining"
},
"X-Rate-Limit-Reset": {
"$ref": "#/components/headers/X-Rate-Limit-Reset"
}
}
},
"422": {
"description": "Unprocessable entity",
"content": {
Expand Down Expand Up @@ -18508,7 +18536,7 @@
"/projects/{project_id}/branches/{name}/compare": {
"get": {
"summary": "Compare branches",
"description": "Compare branch with main branch. \n\n*Note: Comparing a branch may take several minutes depending on the project size.*\n",
"description": "Compare branch with main branch.\n\n*Note: Comparing a branch may take several minutes depending on the project size. Consider using the `POST /compare` endpoint for creating comparison asynchronously.*\n",
"operationId": "branch/compare",
"tags": [
"Branches"
Expand Down Expand Up @@ -18554,6 +18582,10 @@
"404": {
"$ref": "#/components/responses/404"
},
"409": {
"$ref": "#/components/responses/409",
"description": "A comparison is already in progress for this branch."
},
"429": {
"$ref": "#/components/responses/429"
}
Expand All @@ -18569,6 +18601,75 @@
}
],
"x-cli-version": "2.5"
},
"post": {
"summary": "Create comparison (async.)",
"description": "Create a branch comparison asynchronously.\n",
"operationId": "branch/create_comparison",
"tags": [
"Branches"
],
"parameters": [
{
"$ref": "#/components/parameters/X-PhraseApp-OTP"
},
{
"$ref": "#/components/parameters/project_id"
},
{
"$ref": "#/components/parameters/name"
}
],
"responses": {
"200": {
Copy link
Collaborator

@jablan jablan Nov 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

does API ever return 200 here?

Copy link
Member Author

@bikmazefe bikmazefe Nov 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah it used to, but not anymore since we dropped the async switch param. Good catch, thanks!

"$ref": "#/components/responses/200"
},
"202": {
"$ref": "#/components/responses/202"
},
"400": {
"$ref": "#/components/responses/400"
},
"404": {
"$ref": "#/components/responses/404"
},
"409": {
"$ref": "#/components/responses/409",
"description": "An asynchronous comparison is already in progress for this branch."
},
"429": {
"$ref": "#/components/responses/429"
}
},
"x-code-samples": [
{
"lang": "Curl",
"source": "curl \"https://api.phrase.com/v2/projects/:project_id/branches/:name/compare\" \\\n -u USERNAME_OR_ACCESS_TOKEN \\\n -X POST \\\n -d '{\"direction\":\"merge\"}' \\\n -H 'Content-Type: application/json'"
},
{
"lang": "CLI v2",
"source": "phrase branches create_comparison \\\n--project_id <project_id> \\\n--name <name> \\\n--access_token <token>"
}
],
"requestBody": {
"required": true,
Copy link
Collaborator

@jablan jablan Nov 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is this required, considering that the only parameter is optional?

Copy link
Member Author

@bikmazefe bikmazefe Nov 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's not , but the pipeline is failing when this is set to false, I don't remember the exact location of the failure but I can trigger it again. I think that's why we don't have any required: false under requestBody in .yml files (at least I don't see any). I guess we'd need to check this separately 😬

"content": {
"application/json": {
"schema": {
"type": "object",
"title": "branch/create_comparison/parameters",
"properties": {
"direction": {
"description": "direction of comparison, possible values are sync or merge (only for v2 branches, currently in private beta )",
"type": "string",
"example": "merge",
"default": "merge"
}
}
}
}
}
}
}
},
"/accounts": {
Expand Down
2 changes: 2 additions & 0 deletions paths.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -399,6 +399,8 @@
"/projects/{project_id}/branches/{name}/compare":
get:
"$ref": "./paths/branches/compare.yaml"
post:
"$ref": "./paths/branches/create_comparison.yaml"
"/accounts":
get:
"$ref": "./paths/accounts/index.yaml"
Expand Down
9 changes: 6 additions & 3 deletions paths/branches/compare.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
---
summary: Compare branches
description: |
Compare branch with main branch.
*Note: Comparing a branch may take several minutes depending on the project size.*
Compare branch with main branch.

*Note: Comparing a branch may take several minutes depending on the project size. Consider using the `POST /compare` endpoint for creating comparison asynchronously.*
operationId: branch/compare
tags:
- Branches
Expand Down Expand Up @@ -31,6 +31,9 @@ responses:
"$ref": "../../responses.yaml#/400"
'404':
"$ref": "../../responses.yaml#/404"
'409':
"$ref": "../../responses.yaml#/409"
description: A comparison is already in progress for this branch.
'429':
"$ref": "../../responses.yaml#/429"
x-code-samples:
Expand Down
52 changes: 52 additions & 0 deletions paths/branches/create_comparison.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
---
summary: Create comparison (async.)
description: |
Create a branch comparison asynchronously.
operationId: branch/create_comparison
Copy link
Collaborator

@theSoenke theSoenke Nov 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This command looks a bit different than our other commands. Maybe branch/comparison/create would work too?

tags:
- Branches
parameters:
- "$ref": "../../parameters.yaml#/X-PhraseApp-OTP"
- "$ref": "../../parameters.yaml#/project_id"
- "$ref": "../../parameters.yaml#/name"
responses:
'200':
"$ref": "../../responses.yaml#/200"
'202':
"$ref": "../../responses.yaml#/202"
'400':
"$ref": "../../responses.yaml#/400"
'404':
"$ref": "../../responses.yaml#/404"
'409':
"$ref": "../../responses.yaml#/409"
description: An asynchronous comparison is already in progress for this branch.
'429':
"$ref": "../../responses.yaml#/429"
x-code-samples:
- lang: Curl
source: |-
curl "https://api.phrase.com/v2/projects/:project_id/branches/:name/compare" \
-u USERNAME_OR_ACCESS_TOKEN \
-X POST \
-d '{"direction":"merge"}' \
-H 'Content-Type: application/json'
- lang: CLI v2
source: |-
phrase branches create_comparison \
--project_id <project_id> \
--name <name> \
--access_token <token>
requestBody:
required: true
content:
application/json:
schema:
type: object
title: branch/create_comparison/parameters
properties:
direction:
description: direction of comparison, possible values are sync or merge (only for v2 branches, currently in private beta )
type: string
example: merge
default: merge
18 changes: 18 additions & 0 deletions responses.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,15 @@
$ref: "./headers.yaml#/X-Rate-Limit-Remaining"
X-Rate-Limit-Reset:
$ref: "./headers.yaml#/X-Rate-Limit-Reset"
202:
description: Accepted
headers:
X-Rate-Limit-Limit:
$ref: "./headers.yaml#/X-Rate-Limit-Limit"
X-Rate-Limit-Remaining:
$ref: "./headers.yaml#/X-Rate-Limit-Remaining"
X-Rate-Limit-Reset:
$ref: "./headers.yaml#/X-Rate-Limit-Reset"
204:
description: The resource was deleted successfully.
headers:
Expand Down Expand Up @@ -54,6 +63,15 @@
$ref: "./headers.yaml#/X-Rate-Limit-Remaining"
X-Rate-Limit-Reset:
$ref: "./headers.yaml#/X-Rate-Limit-Reset"
409:
description: Conflict
headers:
X-Rate-Limit-Limit:
$ref: "./headers.yaml#/X-Rate-Limit-Limit"
X-Rate-Limit-Remaining:
$ref: "./headers.yaml#/X-Rate-Limit-Remaining"
X-Rate-Limit-Reset:
$ref: "./headers.yaml#/X-Rate-Limit-Reset"
422:
description: Unprocessable entity
content:
Expand Down
Loading