Skip to content

feat(API): improve patch /projects/{project_id}/screenshots/{id} documentation #1190

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

Open
Stephen Lumenta (sbl) wants to merge 1 commit into
base: main
Choose a base branch
from
+125 −76
Open

feat(API): improve patch /projects/{project_id}/screenshots/{id} documentation #1190

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
90 changes: 51 additions & 39 deletions doc/compiled.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21315,7 +21315,7 @@
},
"patch": {
"summary": "Update a screenshot",
"description": "Update an existing screenshot.",
"description": "Updates the name or description of an existing screenshot. This endpoint follows the standard REST resource-update lifecycle: send only the fields you want to change and the server applies them to the existing resource.\n\nUse this when you need to rename a screenshot or revise its contextual description without replacing the image file. Updating screenshot markers is also possible through this endpoint by passing marker attributes. The image file itself cannot be changed; to replace it, delete the screenshot and create a new one.\n\nRequires the Screenshots feature to be enabled on the account and the write scope on the access token. The caller must have manage permission on the project.\n\nThe name must be unique within the project (case-insensitive). Submitting a blank name returns 422. Existing screenshot markers are unaffected unless marker attributes are explicitly passed.\n\n**Errors:** Returns 400 for malformed request parameters — verify parameter names and value types. Returns 401 when no valid access token is supplied — include a valid token and retry. Returns 403 when the Screenshots feature is not enabled on the account or the token lacks the write scope — upgrade the account plan or regenerate the token with the correct scope. Returns 404 when no screenshot with the given id exists in the project — confirm the id is correct for this project. Returns 422 when validation fails, most commonly because the name is blank or already used by another screenshot in the project — choose a non-empty, unique name. Returns 429 when the rate limit is exceeded — wait for the interval indicated in the X-Rate-Limit-Reset response header before retrying.\n",
"operationId": "screenshot/update",
"tags": [
"Screenshots"
Expand All @@ -21331,13 +21331,58 @@
"$ref": "#/components/parameters/id"
}
],
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"title": "screenshot/update/parameters",
"required": [],
"properties": {
"branch": {
"description": "Branch to use for the operation. Omit to update the screenshot on the default branch.",
"type": "string",
"example": "my-feature-branch"
},
"name": {
"description": "New display name for the screenshot. Must be non-empty and unique within the project (case-insensitive). Omit to leave the current name unchanged.",
"type": "string",
"minLength": 1,
"example": "home_screen_v2"
},
"description": {
"description": "Updated description for the screenshot. Omit to leave the current description unchanged.",
"type": "string",
"example": "Updated landing page screenshot"
},
"filename": {
"description": "Screenshot file",
"type": "string",
"format": "binary",
"example": "/path/to/my/screenshot.png"
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/screenshot"
},
"example": {
"id": "d2e056aa9e70b01121f41693e344f5ee",
"name": "home_screen_v2",
"description": "Updated landing page screenshot",
"screenshot_url": "https://assets.phrase.com/screenshots/d2e056aa9e70b01121f41693e344f5ee.png",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-06-14T09:15:00Z",
"markers_count": 3
}
}
},
Expand All @@ -21360,8 +21405,7 @@
"$ref": "#/components/responses/401"
},
"403": {
"$ref": "#/components/responses/403",
"description": "Forbidden. Returned when the access token lacks the `write` scope, when the requesting user is not allowed to update this screenshot, or when the account does not have the Attachable Screenshots feature."
"$ref": "#/components/responses/403"
},
"404": {
"$ref": "#/components/responses/404"
Expand All @@ -21376,47 +21420,15 @@
"x-code-samples": [
{
"lang": "Curl",
"source": "curl \"https://api.phrase.com/v2/projects/:project_id/screenshots/:id\" \\\n -u USERNAME_OR_ACCESS_TOKEN \\\n -X PATCH \\\n -F branch=my-feature-branch \\\n -F name=A%20screenshot%20name \\\n -F description=A%20screenshot%20description \\\n -F filename=@/path/to/my/screenshot.png"
"source": "curl \"https://api.phrase.com/v2/projects/:project_id/screenshots/:id\" \\\n -u USERNAME_OR_ACCESS_TOKEN \\\n -X PATCH \\\n -F \"branch=my-feature-branch\" \\\n -F \"name=home_screen_v2\" \\\n -F \"description=Updated landing page screenshot\"",
"response": "{\n \"id\": \"d2e056aa9e70b01121f41693e344f5ee\",\n \"name\": \"home_screen_v2\",\n \"description\": \"Updated landing page screenshot\",\n \"screenshot_url\": \"https://assets.phrase.com/screenshots/d2e056aa9e70b01121f41693e344f5ee.png\",\n \"created_at\": \"2024-01-15T10:30:00Z\",\n \"updated_at\": \"2024-06-14T09:15:00Z\",\n \"markers_count\": 3\n}"
},
{
"lang": "CLI v2",
"source": "phrase screenshots update \\\n--project_id <project_id> \\\n--id <id> \\\n--data '{\"branch\":\"my-feature-branch\", \"name\": \"A screenshot name\", \"description\": \"A screenshot description\", \"filename\":\"/path/to/my/screenshot.png\"}' \\\n--access_token <token>"
"source": "phrase screenshots update \\\n--project_id abcd1234abcd1234abcd1234abcd1234 \\\n--id d2e056aa9e70b01121f41693e344f5ee \\\n--data '{\"branch\":\"my-feature-branch\",\"name\":\"home_screen_v2\",\"description\":\"Updated landing page screenshot\"}' \\\n--access_token YOUR_ACCESS_TOKEN",
"response": "{\n \"id\": \"d2e056aa9e70b01121f41693e344f5ee\",\n \"name\": \"home_screen_v2\",\n \"description\": \"Updated landing page screenshot\",\n \"screenshot_url\": \"https://assets.phrase.com/screenshots/d2e056aa9e70b01121f41693e344f5ee.png\",\n \"created_at\": \"2024-01-15T10:30:00Z\",\n \"updated_at\": \"2024-06-14T09:15:00Z\",\n \"markers_count\": 3\n}"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"title": "screenshot/update/parameters",
"properties": {
"branch": {
"description": "specify the branch to use",
"type": "string",
"example": "my-feature-branch"
},
"name": {
"description": "Name of the screenshot",
"type": "string",
"example": "A screenshot name"
},
"description": {
"description": "Description of the screenshot",
"type": "string",
"example": "A screenshot description"
},
"filename": {
"description": "Screenshot file",
"type": "string",
"format": "binary",
"example": "/path/to/my/screenshot.png"
}
}
}
}
}
},
"x-cli-version": "2.5"
},
"delete": {
Expand Down
111 changes: 74 additions & 37 deletions paths/screenshots/update.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,20 +1,64 @@
---
summary: Update a screenshot
description: Update an existing screenshot.
description: |
Updates the name or description of an existing screenshot. This endpoint follows the standard REST resource-update lifecycle: send only the fields you want to change and the server applies them to the existing resource.

Use this when you need to rename a screenshot or revise its contextual description without replacing the image file. Updating screenshot markers is also possible through this endpoint by passing marker attributes. The image file itself cannot be changed; to replace it, delete the screenshot and create a new one.

Requires the Screenshots feature to be enabled on the account and the write scope on the access token. The caller must have manage permission on the project.

The name must be unique within the project (case-insensitive). Submitting a blank name returns 422. Existing screenshot markers are unaffected unless marker attributes are explicitly passed.

**Errors:** Returns 400 for malformed request parameters — verify parameter names and value types. Returns 401 when no valid access token is supplied — include a valid token and retry. Returns 403 when the Screenshots feature is not enabled on the account or the token lacks the write scope — upgrade the account plan or regenerate the token with the correct scope. Returns 404 when no screenshot with the given id exists in the project — confirm the id is correct for this project. Returns 422 when validation fails, most commonly because the name is blank or already used by another screenshot in the project — choose a non-empty, unique name. Returns 429 when the rate limit is exceeded — wait for the interval indicated in the X-Rate-Limit-Reset response header before retrying.
operationId: screenshot/update
tags:
- Screenshots
parameters:
- "$ref": "../../parameters.yaml#/X-PhraseApp-OTP"
- "$ref": "../../parameters.yaml#/project_id"
- "$ref": "../../parameters.yaml#/id"
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
title: screenshot/update/parameters
required: []
properties:
branch:
description: Branch to use for the operation. Omit to update the screenshot on the default branch.
type: string
example: my-feature-branch
name:
description: New display name for the screenshot. Must be non-empty and unique within the project (case-insensitive). Omit to leave the current name unchanged.
type: string
minLength: 1
example: home_screen_v2
description:
description: Updated description for the screenshot. Omit to leave the current description unchanged.
type: string
example: Updated landing page screenshot
filename:
description: Screenshot file
type: string
format: binary
example: "/path/to/my/screenshot.png"
responses:
'200':
description: OK
content:
application/json:
schema:
"$ref": "../../schemas/screenshot.yaml#/screenshot"
example:
id: d2e056aa9e70b01121f41693e344f5ee
name: home_screen_v2
description: Updated landing page screenshot
screenshot_url: https://assets.phrase.com/screenshots/d2e056aa9e70b01121f41693e344f5ee.png
created_at: '2024-01-15T10:30:00Z'
updated_at: '2024-06-14T09:15:00Z'
markers_count: 3
headers:
X-Rate-Limit-Limit:
"$ref": "../../headers.yaml#/X-Rate-Limit-Limit"
Expand All @@ -24,13 +68,12 @@ responses:
"$ref": "../../headers.yaml#/X-Rate-Limit-Reset"
'400':
"$ref": "../../responses.yaml#/400"
'404':
"$ref": "../../responses.yaml#/404"
'401':
"$ref": "../../responses.yaml#/401"
'403':
"$ref": "../../responses.yaml#/403"
description: Forbidden. Returned when the access token lacks the `write` scope, when the requesting user is not allowed to update this screenshot, or when the account does not have the Attachable Screenshots feature.
'404':
"$ref": "../../responses.yaml#/404"
'422':
"$ref": "../../responses.yaml#/422"
'429':
Expand All @@ -41,40 +84,34 @@ x-code-samples:
curl "https://api.phrase.com/v2/projects/:project_id/screenshots/:id" \
-u USERNAME_OR_ACCESS_TOKEN \
-X PATCH \
-F branch=my-feature-branch \
-F name=A%20screenshot%20name \
-F description=A%20screenshot%20description \
-F filename=@/path/to/my/screenshot.png
-F "branch=my-feature-branch" \
-F "name=home_screen_v2" \
-F "description=Updated landing page screenshot"
response: |-
{
"id": "d2e056aa9e70b01121f41693e344f5ee",
"name": "home_screen_v2",
"description": "Updated landing page screenshot",
"screenshot_url": "https://assets.phrase.com/screenshots/d2e056aa9e70b01121f41693e344f5ee.png",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-06-14T09:15:00Z",
"markers_count": 3
}
- lang: CLI v2
source: |-
phrase screenshots update \
--project_id <project_id> \
--id <id> \
--data '{"branch":"my-feature-branch", "name": "A screenshot name", "description": "A screenshot description", "filename":"/path/to/my/screenshot.png"}' \
--access_token <token>
requestBody:
required: true
content:
application/json:
schema:
type: object
title: screenshot/update/parameters
properties:
branch:
description: specify the branch to use
type: string
example: my-feature-branch
name:
description: Name of the screenshot
type: string
example: A screenshot name
description:
description: Description of the screenshot
type: string
example: A screenshot description
filename:
description: Screenshot file
type: string
format: binary
example: "/path/to/my/screenshot.png"
--project_id abcd1234abcd1234abcd1234abcd1234 \
--id d2e056aa9e70b01121f41693e344f5ee \
--data '{"branch":"my-feature-branch","name":"home_screen_v2","description":"Updated landing page screenshot"}' \
--access_token YOUR_ACCESS_TOKEN
response: |-
{
"id": "d2e056aa9e70b01121f41693e344f5ee",
"name": "home_screen_v2",
"description": "Updated landing page screenshot",
"screenshot_url": "https://assets.phrase.com/screenshots/d2e056aa9e70b01121f41693e344f5ee.png",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-06-14T09:15:00Z",
"markers_count": 3
}
x-cli-version: '2.5'
Loading