feat(API): add Custom Metadata endpoints (#474)

* register Custom Metadata Labels to main yml

* add custom metadata schema

* add custom metadata index path

* add enum for data_type

* specify 2.9 cli version

* generalize custom metadata tag

* correct path for index route

* update path

* update compiled json

* align Custom Metadata tag usage

* add project ids param to labels index

* add sort and order to metadata label index

* update url params example

* make summary and description more clear and concise

* add endpoint availability notice

* remove account ref from schema

* add projects to custom metadata label schema

* update label -> property

* rename CM paths folder

* fix parameter definitions

* feat(api): Add show API endpoint for custom_metadata_labels (#359)

* add paths for custom metadata show

* make summary and description more clear and concise

* fix path with namespace

* change from label to property for consistency

* remove unused branch param

---------

Co-authored-by: Matias Alvarez <[email protected]>

* feat: add CM api update (#475)

* add name and description

* add create api doc for CM properties (#476)

* feat:  add delete CM property doc (#477)

* add delete api doc for CM properties

* rename data type to custom metadata data type

* nest create under collection

* update routes to use properties instead of labels

* fix project_id example

* update path CM route naming

* feat: update translation key create/update with custom metadata. Add CM schema in translation key response (#480)

* add CM to create/update keys

* Add custom metadata object on CM get key

* Add more description for update

---------

Co-authored-by: Ildar Safin <[email protected]>

* Make create CM example to be working with CURL

* Make the data_type field to be not required

* extract custom metadata data type schema

---------

Co-authored-by: Matias Alvarez <[email protected]>
Co-authored-by: Ildar Safin <[email protected]>
Co-authored-by: Mladen Jablanovic <[email protected]>

main.yaml

@@ -114,6 +114,7 @@ tags:
   - name: Comments
   - name: Comment Reactions
   - name: Comment Replies
+  - name: Custom Metadata
   - name: Distributions
   - name: Documents
   - name: Figma Attachments
@@ -266,6 +267,7 @@ x-tagGroups:
       - Translations
       - Uploads
       - Tags
+      - Custom Metadata Properties
       - Blacklisted Keys
       - Versions / History
   - name: Workflows

parameters.yaml

@@ -31,6 +31,14 @@ account_id:
   required: true
   schema:
     type: string
+custom_metadata_data_type:
+  in: query
+  name: data_type
+  description: Data Type of Custom Metadata Property
+  required: false
+  schema:
+    "$ref": "./schemas/custom_metadata_data_type.yaml#/data_type"
+  example: boolean
 query_account_id:
   in: query
   name: account_id

paths.yaml

@@ -47,6 +47,18 @@
     "$ref": "./paths/styleguides/update.yaml"
   delete:
     "$ref": "./paths/styleguides/destroy.yaml"
+"/accounts/{account_id}/custom_metadata/properties":
+  get:
+    "$ref": "./paths/custom_metadata_properties/index.yaml"
+  post:
+    "$ref": "./paths/custom_metadata_properties/create.yaml"
+"/accounts/{account_id}/custom_metadata/properties/{id}":
+  get:
+    "$ref": "./paths/custom_metadata_properties/show.yaml"
+  patch:
+    "$ref": "./paths/custom_metadata_properties/update.yaml"
+  delete:
+    "$ref": "./paths/custom_metadata_properties/destroy.yaml"
 "/accounts/{account_id}/invitations":
   get:
     "$ref": "./paths/invitations/index.yaml"

paths/custom_metadata_properties/create.yaml

@@ -0,0 +1,88 @@
+---
+summary: Create a property
+description: Create a new custom metadata property.
+operationId: custom_metadata_property/create
+tags:
+- Custom Metadata
+parameters:
+- "$ref": "../../parameters.yaml#/X-PhraseApp-OTP"
+- "$ref": "../../parameters.yaml#/account_id"
+- description: name of the property
+  example:
+  - Fruit
+  name: name
+  in: query
+  required: true
+  schema:
+    type: string
+- name: data_type
+  in: query
+  description: Data Type of Custom Metadata Property
+  required: true
+  schema:
+    "$ref": "../../schemas/custom_metadata_data_type.yaml#/data_type"
+  example: boolean
+- description: description of property
+  example:
+  - A healthy snack for all ages
+  name: description
+  in: query
+  schema:
+    type: string
+- description: ids of projects that the property belongs to
+  example:
+    - abcd1234cdef1234abcd1234cdef1234
+  name: project_ids
+  in: query
+  schema:
+    type: array
+    items:
+      type: string
+- description: value options of property (only applies to single or multi select properties)
+  example:
+    - Apple
+    - Banana
+    - Coconut
+  name: value_options
+  in: query
+  schema:
+    type: array
+    items:
+      type: string
+responses:
+  '200':
+    description: OK
+    content:
+      application/json:
+        schema:
+          "$ref": "../../schemas/custom_metadata_property.yaml#/custom_metadata_property"
+    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"
+  '400':
+    "$ref": "../../responses.yaml#/400"
+  '404':
+    "$ref": "../../responses.yaml#/404"
+  '422':
+    "$ref": "../../responses.yaml#/422"
+  '429':
+    "$ref": "../../responses.yaml#/429"
+x-code-samples:
+- lang: Curl
+  source: |-
+    curl "https://api.phrase.com/v2/accounts/:account_id/custom_metadata/properties" \
+      -u USERNAME_OR_ACCESS_TOKEN \
+      -X POST \
+      -d '{"name":"Fruit","data_type":"multi_select","description":"A healthy snack for all ages","project_ids":["1","2","3"],"value_options":["apple","banana","coconut"]}' \
+      -H 'Content-Type: application/json'
+- lang: CLI v2
+  source: |-
+    phrase custom_metadata_properties create \
+    --account_id <account_id> \
+    --data '{"name":"Fruit","data_type":"multi_select","description":"A healthy snack for all ages","project_ids":["1","2","3"],"value_options":["apple","banana","coconut"]}' \
+    --access_token <token>
+x-cli-version: '2.9'

paths/custom_metadata_properties/destroy.yaml

@@ -0,0 +1,36 @@
+---
+summary: Destroy property
+description: |
+  Destroy a custom metadata property of an account.
+
+  This endpoint is only available to accounts with advanced plans or above.
+operationId: custom_metadata_properties/delete
+tags:
+- Custom Metadata
+parameters:
+- "$ref": "../../parameters.yaml#/X-PhraseApp-OTP"
+- "$ref": "../../parameters.yaml#/account_id"
+- "$ref": "../../parameters.yaml#/id"
+responses:
+  '204':
+    "$ref": "../../responses.yaml#/204"
+  '400':
+    "$ref": "../../responses.yaml#/400"
+  '404':
+    "$ref": "../../responses.yaml#/404"
+  '429':
+    "$ref": "../../responses.yaml#/429"
+x-code-samples:
+- lang: Curl
+  source: |-
+    curl "https://api.phrase.com/v2/accounts/:account_id/custom_metadata/properties/:id" \
+      -u USERNAME_OR_ACCESS_TOKEN
+      -X DELETE
+      -H 'Content-Type: application/json'
+- lang: CLI v2
+  source: |-
+    phrase custom_metadata_properties delete \
+    --account_id <account_id> \
+    --id <id> \
+    --access_token <token>
+x-cli-version: '2.9'

paths/custom_metadata_properties/index.yaml

@@ -0,0 +1,74 @@
+---
+summary: List properties
+description: |
+  List all custom metadata properties for an account.
+
+  This endpoint is only available to accounts with advanced plans or above.
+operationId: custom_metadata_properties/list
+tags:
+- Custom Metadata
+parameters:
+- "$ref": "../../parameters.yaml#/X-PhraseApp-OTP"
+- "$ref": "../../parameters.yaml#/account_id"
+- "$ref": "../../parameters.yaml#/custom_metadata_data_type"
+- description: id of project that the properties belong to
+  example: abcd1234cdef1234abcd1234cdef1234
+  name: project_id
+  in: query
+  schema:
+    type: string
+- "$ref": "../../parameters.yaml#/page"
+- "$ref": "../../parameters.yaml#/per_page"
+- description: 'Sort criteria. Can be one of: name, data_type, created_at.'
+  example: updated_at
+  name: sort
+  in: query
+  schema:
+    type: string
+- description: 'Order direction. Can be one of: asc, desc.'
+  example: desc
+  name: order
+  in: query
+  schema:
+    type: string
+responses:
+  '200':
+    description: OK
+    content:
+      application/json:
+        schema:
+          type: array
+          items:
+            "$ref": "../../schemas/custom_metadata_property.yaml#/custom_metadata_property"
+    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"
+      Link:
+        "$ref": "../../headers.yaml#/Link"
+  '400':
+    "$ref": "../../responses.yaml#/400"
+  '404':
+    "$ref": "../../responses.yaml#/404"
+  '429':
+    "$ref": "../../responses.yaml#/429"
+x-code-samples:
+- lang: Curl
+  source: |-
+    curl "https://api.phrase.com/v2/accounts/:account_id/custom_metadata/properties?data_type=boolean&project_id=1&page=1&per_page=10&sort=created_at&order=desc" \
+      -u USERNAME_OR_ACCESS_TOKEN
+- lang: CLI v2
+  source: |-
+    phrase custom_metadata_properties list \
+    --account_id <account_id> \
+    --data_type boolean \
+    --project_id 1 \
+    --page 1 \
+    --per_page 10 \
+    --sort created_at \
+    --order desc \
+    --access_token <token>
+x-cli-version: '2.9'

paths/custom_metadata_properties/show.yaml

@@ -0,0 +1,42 @@
+---
+summary: Get a single property
+description: Get details of a single custom property.
+operationId: custom_metadata_property/show
+tags:
+- Custom Metadata
+parameters:
+- "$ref": "../../parameters.yaml#/X-PhraseApp-OTP"
+- "$ref": "../../parameters.yaml#/account_id"
+- "$ref": "../../parameters.yaml#/id"
+responses:
+  '200':
+    description: OK
+    content:
+      application/json:
+        schema:
+          "$ref": "../../schemas/custom_metadata_property.yaml#/custom_metadata_property"
+    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"
+  '400':
+    "$ref": "../../responses.yaml#/400"
+  '404':
+    "$ref": "../../responses.yaml#/404"
+  '429':
+    "$ref": "../../responses.yaml#/429"
+x-code-samples:
+- lang: Curl
+  source: |-
+    curl "https://api.phrase.com/v2/accounts/:account_id/custom_metadata/properties/:id" \
+      -u USERNAME_OR_ACCESS_TOKEN
+- lang: CLI v2
+  source: |-
+    phrase custom_metadata_properties show \
+    --account_id <account_id> \
+    --id <id> \
+    --access_token <token>
+x-cli-version: '2.9'

paths/custom_metadata_properties/update.yaml

@@ -0,0 +1,80 @@
+---
+summary: Update a property
+description: Update an existing custom metadata property.
+operationId: custom_metadata_property/update
+tags:
+- Custom Metadata
+parameters:
+- "$ref": "../../parameters.yaml#/X-PhraseApp-OTP"
+- "$ref": "../../parameters.yaml#/account_id"
+- "$ref": "../../parameters.yaml#/id"
+- description: name of the property
+  example:
+  - Fruit
+  name: name
+  in: query
+  schema:
+    type: string
+- description: description of property
+  example:
+  - A healthy snack for all ages
+  name: description
+  in: query
+  schema:
+    type: string
+- description: ids of projects that the property belongs to
+  example:
+    - abcd1234cdef1234abcd1234cdef1234
+  name: project_ids
+  in: query
+  schema:
+    type: array
+    items:
+      type: string
+- description: value options of property (only applies to single or multi select properties)
+  example:
+    - Apple
+    - Banana
+    - Coconut
+  name: value_options
+  in: query
+  schema:
+    type: array
+    items:
+      type: string
+responses:
+  '200':
+    description: OK
+    content:
+      application/json:
+        schema:
+          "$ref": "../../schemas/custom_metadata_property.yaml#/custom_metadata_property"
+    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"
+  '400':
+    "$ref": "../../responses.yaml#/400"
+  '404':
+    "$ref": "../../responses.yaml#/404"
+  '429':
+    "$ref": "../../responses.yaml#/429"
+x-code-samples:
+- lang: Curl
+  source: |-
+    curl "https://api.phrase.com/v2/accounts/:account_id/custom_metadata/properties/:id" \
+      -u USERNAME_OR_ACCESS_TOKEN \
+      -X PATCH \
+      -d '{"name":"Fruit","description":"A healthy snack for all ages","project_ids":["1","2","3"],"value_options":["apple","banana","coconut"]}' \
+      -H 'Content-Type: application/json'
+- lang: CLI v2
+  source: |-
+    phrase custom_metadata_properties update \
+    --account_id <account_id> \
+    --id <id> \
+    --data '{"name":"Fruit","description":"A healthy snack for all ages","project_ids":["1","2","3"],"value_options":["apple","banana","coconut"]}' \
+    --access_token <token>
+x-cli-version: '2.9'