Skip to content

Commit 95b6c2a

Browse files
BlumMichaelBlumMichael
authored
feat(API): Job and job locale annotations #SCD-145 (#867)
1 parent 3a49bbc commit 95b6c2a

File tree

18 files changed

+971
-13
lines changed

18 files changed

+971
-13
lines changed

‎doc/compiled.json‎

Lines changed: 560 additions & 7 deletions
Large diffs are not rendered by default.

‎main.yaml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -124,6 +124,9 @@ tags:
124124
- name: Invitations
125125
description: |
126126
With the invitation endpoint you can [manage and invite users](https://support.phrase.com/hc/en-us/articles/5709742418716) to Phrase Strings via API. A user can have the role Manager, Developer or Translator each with its own access rights. Developers and translators need resources like projects and locales assigned in order to access them.
127+
- name: Job Annotations
128+
description: |
129+
The job annotations endpoints allow you to create, update and delete annotations for jobs and job locales. Annotations are used to add metadata to a job or job locale.
127130
- name: Job Comments
128131
- name: Job Locales
129132
- name: Job Template Locales

‎parameters.yaml‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -102,6 +102,13 @@ job_id:
102102
required: true
103103
schema:
104104
type: string
105+
job_locale_id:
106+
in: path
107+
name: job_locale_id
108+
description: Job Locale ID
109+
required: true
110+
schema:
111+
type: string
105112
job_template_id:
106113
in: path
107114
name: job_template_id
@@ -288,3 +295,11 @@ job_updated_since:
288295
in: query
289296
schema:
290297
type: string
298+
include_annotations:
299+
in: query
300+
name: include_annotations
301+
description: Include job-locale annotations in the response
302+
required: false
303+
schema:
304+
type: boolean
305+
default: false

‎paths.yaml‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -350,6 +350,22 @@
350350
"$ref": "./paths/job_template_locales/update.yaml"
351351
delete:
352352
"$ref": "./paths/job_template_locales/destroy.yaml"
353+
"/projects/{project_id}/jobs/{job_id}/annotations":
354+
get:
355+
"$ref": "./paths/job_annotations/index.yaml"
356+
"/projects/{project_id}/jobs/{job_id}/annotations/{id}":
357+
patch:
358+
"$ref": "./paths/job_annotations/update.yaml"
359+
delete:
360+
"$ref": "./paths/job_annotations/destroy.yaml"
361+
"/projects/{project_id}/jobs/{job_id}/locales/{job_locale_id}/annotations":
362+
get:
363+
"$ref": "./paths/job_locale_annotations/index.yaml"
364+
"/projects/{project_id}/jobs/{job_id}/locales/{job_locale_id}/annotations/{id}":
365+
patch:
366+
"$ref": "./paths/job_locale_annotations/update.yaml"
367+
delete:
368+
"$ref": "./paths/job_locale_annotations/destroy.yaml"
353369
"/projects/{project_id}/variables":
354370
get:
355371
"$ref": "./paths/variables/index.yaml"

‎paths/job_annotations/destroy.yaml‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
---
2+
summary: Delete a job annotation
3+
description: Delete an annotation for a job.
4+
operationId: job_annotation/delete
5+
tags:
6+
- Job Annotations
7+
parameters:
8+
- "$ref": "../../parameters.yaml#/X-PhraseApp-OTP"
9+
- "$ref": "../../parameters.yaml#/project_id"
10+
- "$ref": "../../parameters.yaml#/branch"
11+
- "$ref": "../../parameters.yaml#/job_id"
12+
- name: id
13+
in: path
14+
required: true
15+
description: Name of the annotation to delete.
16+
schema:
17+
type: string
18+
responses:
19+
'204':
20+
description: No Content
21+
headers:
22+
X-Rate-Limit-Limit:
23+
"$ref": "../../headers.yaml#/X-Rate-Limit-Limit"
24+
X-Rate-Limit-Remaining:
25+
"$ref": "../../headers.yaml#/X-Rate-Limit-Remaining"
26+
X-Rate-Limit-Reset:
27+
"$ref": "../../headers.yaml#/X-Rate-Limit-Reset"
28+
'400':
29+
"$ref": "../../responses.yaml#/400"
30+
'404':
31+
"$ref": "../../responses.yaml#/404"
32+
'429':
33+
"$ref": "../../responses.yaml#/429"
34+
x-code-samples:
35+
- lang: Curl
36+
source: |-
37+
curl "https://api.phrase.com/v2/projects/:project_id/jobs/:job_id/annotations/:id" \
38+
-u USERNAME_OR_ACCESS_TOKEN \
39+
-X DELETE
40+
- lang: CLI v2
41+
source: |-
42+
phrase job_annotations delete \
43+
--project_id <project_id> \
44+
--job_id <job_id> \
45+
--id <id> \
46+
--access_token <token>
47+
x-cli-version: '2.43'

‎paths/job_annotations/index.yaml‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
summary: List job annotations
3+
description: Retrieve a list of annotations for a job.
4+
operationId: job_annotations/list
5+
tags:
6+
- Job Annotations
7+
parameters:
8+
- "$ref": "../../parameters.yaml#/X-PhraseApp-OTP"
9+
- "$ref": "../../parameters.yaml#/project_id"
10+
- "$ref": "../../parameters.yaml#/branch"
11+
- "$ref": "../../parameters.yaml#/job_id"
12+
responses:
13+
'200':
14+
description: OK
15+
content:
16+
application/json:
17+
schema:
18+
type: array
19+
items:
20+
"$ref": "../../schemas/job_annotation.yaml#/job_annotation"
21+
headers:
22+
X-Rate-Limit-Limit:
23+
"$ref": "../../headers.yaml#/X-Rate-Limit-Limit"
24+
X-Rate-Limit-Remaining:
25+
"$ref": "../../headers.yaml#/X-Rate-Limit-Remaining"
26+
X-Rate-Limit-Reset:
27+
"$ref": "../../headers.yaml#/X-Rate-Limit-Reset"
28+
x-code-samples:
29+
- lang: Curl
30+
source: |-
31+
curl "https://api.phrase.com/v2/projects/:project_id/jobs/:job_id/annotations" \
32+
-u USERNAME_OR_ACCESS_TOKEN \
33+
-X GET
34+
- lang: CLI v2
35+
source: |-
36+
phrase job_annotations list \
37+
--project_id <project_id> \
38+
--job_id <job_id> \
39+
--access_token <token>
40+
x-cli-version: '2.43'

‎paths/job_annotations/update.yaml‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
---
2+
summary: Create/Update a job annotation
3+
description: Create or update an annotation for a job. If the annotation already exists, it will be updated; otherwise, a new annotation will be created.
4+
operationId: job_annotation/update
5+
tags:
6+
- Job Annotations
7+
parameters:
8+
- "$ref": "../../parameters.yaml#/X-PhraseApp-OTP"
9+
- "$ref": "../../parameters.yaml#/project_id"
10+
- "$ref": "../../parameters.yaml#/job_id"
11+
- name: id
12+
in: path
13+
required: true
14+
description: Name of the annotation to set or update.
15+
schema:
16+
type: string
17+
responses:
18+
'200':
19+
description: OK
20+
content:
21+
application/json:
22+
schema:
23+
"$ref": "../../schemas/job_annotation.yaml#/job_annotation"
24+
headers:
25+
X-Rate-Limit-Limit:
26+
"$ref": "../../headers.yaml#/X-Rate-Limit-Limit"
27+
X-Rate-Limit-Remaining:
28+
"$ref": "../../headers.yaml#/X-Rate-Limit-Remaining"
29+
X-Rate-Limit-Reset:
30+
"$ref": "../../headers.yaml#/X-Rate-Limit-Reset"
31+
'400':
32+
"$ref": "../../responses.yaml#/400"
33+
'404':
34+
"$ref": "../../responses.yaml#/404"
35+
'429':
36+
"$ref": "../../responses.yaml#/429"
37+
x-code-samples:
38+
- lang: Curl
39+
source: |-
40+
curl "https://api.phrase.com/v2/projects/:project_id/jobs/:job_id/annotations/:id" \
41+
-u USERNAME_OR_ACCESS_TOKEN \
42+
-X PATCH \
43+
-d '{"value":"Some value..."}' \
44+
-H 'Content-Type: application/json'
45+
- lang: CLI v2
46+
source: |-
47+
phrase job_annotations update \
48+
--project_id <project_id> \
49+
--job_id <job_id> \
50+
--id <id> \
51+
--data '{"value": "Some value..."}' \
52+
--access_token <token>
53+
requestBody:
54+
required: true
55+
content:
56+
application/json:
57+
schema:
58+
type: object
59+
title: job_annotation/update/parameters
60+
properties:
61+
value:
62+
description: Annotation value
63+
type: string
64+
example: Some value...
65+
branch:
66+
description: Branch name of the job
67+
type: string
68+
example: my-feature-branch
69+
x-cli-version: '2.43'

‎paths/job_locale_annotations/destroy.yaml‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
---
2+
summary: Delete a job locale annotation
3+
description: Delete an annotation for a job locale.
4+
operationId: job_locale_annotation/delete
5+
tags:
6+
- Job Annotations
7+
parameters:
8+
- "$ref": "../../parameters.yaml#/X-PhraseApp-OTP"
9+
- "$ref": "../../parameters.yaml#/project_id"
10+
- "$ref": "../../parameters.yaml#/branch"
11+
- "$ref": "../../parameters.yaml#/job_id"
12+
- "$ref": "../../parameters.yaml#/job_locale_id"
13+
- name: id
14+
in: path
15+
required: true
16+
description: Name of the annotation to delete.
17+
schema:
18+
type: string
19+
responses:
20+
'204':
21+
description: No Content
22+
headers:
23+
X-Rate-Limit-Limit:
24+
"$ref": "../../headers.yaml#/X-Rate-Limit-Limit"
25+
X-Rate-Limit-Remaining:
26+
"$ref": "../../headers.yaml#/X-Rate-Limit-Remaining"
27+
X-Rate-Limit-Reset:
28+
"$ref": "../../headers.yaml#/X-Rate-Limit-Reset"
29+
'400':
30+
"$ref": "../../responses.yaml#/400"
31+
'404':
32+
"$ref": "../../responses.yaml#/404"
33+
'429':
34+
"$ref": "../../responses.yaml#/429"
35+
x-code-samples:
36+
- lang: Curl
37+
source: |-
38+
curl "https://api.phrase.com/v2/projects/:project_id/jobs/:job_id/locales/:job_locale_id/annotations/:id" \
39+
-u USERNAME_OR_ACCESS_TOKEN \
40+
-X DELETE
41+
- lang: CLI v2
42+
source: |-
43+
phrase job_locale_annotations delete \
44+
--project_id <project_id> \
45+
--job_id <job_id> \
46+
--job_locale_id <job_locale_id> \
47+
--id <id> \
48+
--access_token <token>
49+
x-cli-version: '2.43'

‎paths/job_locale_annotations/index.yaml‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
---
2+
summary: List job locale annotations
3+
description: Retrieve a list of annotations for a job locale.
4+
operationId: job_locale_annotations/list
5+
tags:
6+
- Job Annotations
7+
parameters:
8+
- "$ref": "../../parameters.yaml#/X-PhraseApp-OTP"
9+
- "$ref": "../../parameters.yaml#/project_id"
10+
- "$ref": "../../parameters.yaml#/branch"
11+
- "$ref": "../../parameters.yaml#/job_id"
12+
- "$ref": "../../parameters.yaml#/job_locale_id"
13+
responses:
14+
'200':
15+
description: OK
16+
content:
17+
application/json:
18+
schema:
19+
type: array
20+
items:
21+
"$ref": "../../schemas/job_annotation.yaml#/job_annotation"
22+
headers:
23+
X-Rate-Limit-Limit:
24+
"$ref": "../../headers.yaml#/X-Rate-Limit-Limit"
25+
X-Rate-Limit-Remaining:
26+
"$ref": "../../headers.yaml#/X-Rate-Limit-Remaining"
27+
X-Rate-Limit-Reset:
28+
"$ref": "../../headers.yaml#/X-Rate-Limit-Reset"
29+
x-code-samples:
30+
- lang: Curl
31+
source: |-
32+
curl "https://api.phrase.com/v2/projects/:project_id/jobs/:job_id/locales/:job_locale_id/annotations" \
33+
-u USERNAME_OR_ACCESS_TOKEN \
34+
-X GET
35+
- lang: CLI v2
36+
source: |-
37+
phrase job_locale_annotations list \
38+
--project_id <project_id> \
39+
--job_id <job_id> \
40+
--job_locale_id <job_locale_id> \
41+
--access_token <token>
42+
x-cli-version: '2.43'

‎paths/job_locale_annotations/update.yaml‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
---
2+
summary: Create/Update a job locale annotation
3+
description: Create or update an annotation for a job locale. If the annotation already exists, it will be updated; otherwise, a new annotation will be created.
4+
operationId: job_locale_annotation/update
5+
tags:
6+
- Job Annotations
7+
parameters:
8+
- "$ref": "../../parameters.yaml#/X-PhraseApp-OTP"
9+
- "$ref": "../../parameters.yaml#/project_id"
10+
- "$ref": "../../parameters.yaml#/job_id"
11+
- "$ref": "../../parameters.yaml#/job_locale_id"
12+
- name: id
13+
in: path
14+
required: true
15+
description: Name of the annotation to set or update.
16+
schema:
17+
type: string
18+
responses:
19+
'200':
20+
description: OK
21+
content:
22+
application/json:
23+
schema:
24+
"$ref": "../../schemas/job_annotation.yaml#/job_annotation"
25+
headers:
26+
X-Rate-Limit-Limit:
27+
"$ref": "../../headers.yaml#/X-Rate-Limit-Limit"
28+
X-Rate-Limit-Remaining:
29+
"$ref": "../../headers.yaml#/X-Rate-Limit-Remaining"
30+
X-Rate-Limit-Reset:
31+
"$ref": "../../headers.yaml#/X-Rate-Limit-Reset"
32+
'400':
33+
"$ref": "../../responses.yaml#/400"
34+
'404':
35+
"$ref": "../../responses.yaml#/404"
36+
'429':
37+
"$ref": "../../responses.yaml#/429"
38+
x-code-samples:
39+
- lang: Curl
40+
source: |-
41+
curl "https://api.phrase.com/v2/projects/:project_id/jobs/:job_id/locales/:job_locale_id/annotations/:id" \
42+
-u USERNAME_OR_ACCESS_TOKEN \
43+
-X PATCH \
44+
-d '{"value":"Some value..."}' \
45+
-H 'Content-Type: application/json'
46+
- lang: CLI v2
47+
source: |-
48+
phrase job_locale_annotations update \
49+
--project_id <project_id> \
50+
--job_id <job_id> \
51+
--job_locale_id <job_locale_id> \
52+
--id <id> \
53+
--data '{"value": "Some value..."}' \
54+
--access_token <token>
55+
requestBody:
56+
required: true
57+
content:
58+
application/json:
59+
schema:
60+
type: object
61+
title: job_annotation/update/parameters
62+
properties:
63+
value:
64+
description: Annotation value
65+
type: string
66+
example: Some value...
67+
branch:
68+
description: Branch name of the job
69+
type: string
70+
example: my-feature-branch
71+
x-cli-version: '2.43'

0 commit comments

Comments
 (0)