Skip to content

Commit

Permalink
feat(API): Async downloads [TSI-2515] (#642)
Browse files Browse the repository at this point in the history
  • Loading branch information
@jablan
jablan authored Jun 25, 2024
1 parent 3d4d955 commit 6fcab5d
Show file tree
Hide file tree
Showing 7 changed files with 556 additions and 0 deletions.
319 changes: 319 additions & 0 deletions doc/compiled.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -115,9 +115,15 @@
{
"name": "Keys"
},
{
"name": "Linked Keys"
},
{
"name": "Locales"
},
{
"name": "Locale Downloads"
},
{
"name": "Members",
"description": "With the members endpoints you can do basic [team and user management](https://support.phrase.com/hc/en-us/articles/5709742418716) 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.\n"
Expand Down Expand Up @@ -1699,6 +1705,90 @@
"updated_at": "2015-01-28T09:52:53Z"
}
},
"locale_download": {
"type": "object",
"title": "Async Locale Download",
"properties": {
"id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"processing",
"completed",
"error"
],
"description": "The status of the download request. Possible values are `processing`, `completed`, and `error`.\n"
},
"result": {
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "The URL to the download file. This URL is valid for 15 minutes.\n"
}
}
},
"params": {
"type": "object",
"description": "The parameters of the download request.\n",
"properties": {
"file_format": {
"type": "string"
},
"locale_id": {
"type": "string"
},
"tags": {
"type": "string"
},
"branch": {
"type": "string"
},
"include_empty_translations": {
"type": "boolean"
},
"include_translated_keys": {
"type": "boolean"
},
"include_unverified_translations": {
"type": "boolean"
}
}
},
"error": {
"type": "string"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"completed_at": {
"type": "string",
"format": "date-time"
}
},
"example": {
"id": "abcd1234cdef1234abcd1234cdef1234",
"status": "completed",
"result": {
"url": "https://example.com/locales/abcd1234cdef1234abcd1234cdef1234/download?file_format=yml"
},
"params": {
"file_format": "yml",
"locale_id": "abcd1234cdef1234abcd1234cdef1234",
"tags": "feature1,feature2",
"branch": "my-feature-branch",
"include_empty_translations": true,
"include_translated_keys": true,
"include_unverified_translations": true
},
"created_at": "2015-01-28T09:52:53Z",
"completed_at": "2015-01-28T09:52:53Z"
}
},
"locale_statistics": {
"type": "object",
"title": "locale_statistics",
Expand Down Expand Up @@ -8731,6 +8821,235 @@
"x-cli-version": "2.6.4"
}
},
"/projects/{project_id}/locales/{locale_id}/downloads": {
"post": {
"summary": "Initiate async download of a locale",
"description": "Prepare a locale for download in a specific file format.",
"operationId": "locale_download/create",
"tags": [
"Locale Downloads"
],
"parameters": [
{
"$ref": "#/components/parameters/X-PhraseApp-OTP"
},
{
"$ref": "#/components/parameters/If-Modified-Since"
},
{
"$ref": "#/components/parameters/If-None-Match"
},
{
"$ref": "#/components/parameters/project_id"
},
{
"$ref": "#/components/parameters/locale_id"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"title": "locale_download/create/parameters",
"required": [
"file_format"
],
"properties": {
"file_format": {
"description": "File format name. See the <a href=\"https://support.phrase.com/hc/en-us/sections/6111343326364\">format guide</a> for all supported file formats.",
"type": "string",
"example": "yml"
},
"branch": {
"description": "specify the branch to use",
"type": "string",
"example": "my-feature-branch"
},
"tags": {
"description": "Limit results to keys tagged with a list of comma separated tag names.",
"type": "string",
"example": "feature1,feature2"
},
"include_empty_translations": {
"description": "Indicates whether keys without translations should be included in the output as well.",
"example": true,
"type": "boolean"
},
"exclude_empty_zero_forms": {
"description": "Indicates whether zero forms should be included when empty in pluralized keys.",
"example": true,
"type": "boolean"
},
"include_translated_keys": {
"description": "Include translated keys in the locale file. Use in combination with include_empty_translations to obtain only untranslated keys.",
"example": true,
"type": "boolean"
},
"keep_notranslate_tags": {
"description": "Indicates whether [NOTRANSLATE] tags should be kept.",
"type": "boolean",
"example": true
},
"format_options": {
"description": "Additional formatting and render options. See the <a href=\"https://support.phrase.com/hc/en-us/sections/6111343326364\">format guide</a> for a list of options available for each format. Specify format options like this: <code>...&format_options[foo]=bar</code>",
"type": "object",
"properties": {}
},
"encoding": {
"description": "Enforces a specific encoding on the file contents. Valid options are \"UTF-8\", \"UTF-16\" and \"ISO-8859-1\".",
"example": "UTF-8",
"type": "string"
},
"include_unverified_translations": {
"description": "if set to false unverified translations are excluded",
"example": true,
"type": "boolean"
},
"use_last_reviewed_version": {
"description": "If set to true the last reviewed version of a translation is used. This is only available if the review workflow is enabled for the project.",
"type": "boolean",
"example": null
},
"fallback_locale_id": {
"description": "If a key has no translation in the locale being downloaded the translation in the fallback locale will be used. Provide the ID of the locale that should be used as the fallback. Requires include_empty_translations to be set to <code>true</code>.",
"type": "string",
"example": "abcd1234abcd1234abcd1234abcd1234"
},
"source_locale_id": {
"description": "Provides the source language of a corresponding job as the source language of the generated locale file. This parameter will be ignored unless used in combination with a <code>tag</code> parameter indicating a specific job.",
"example": "abcd1234abcd1234abcd1234abcd1234",
"type": "string"
},
"custom_metadata_filters": {
"description": "Custom metadata filters. Provide the name of the metadata field and the value to filter by. Only keys with matching metadata will be included in the download.\n",
"type": "object",
"properties": {}
}
}
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/locale_download"
}
}
},
"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"
}
}
},
"400": {
"$ref": "#/components/responses/400"
},
"404": {
"$ref": "#/components/responses/404"
},
"429": {
"$ref": "#/components/responses/429"
}
},
"x-code-samples": [
{
"lang": "Curl",
"source": "\ncurl \"https://api.phrase.com/v2/projects/:project_id/locales/:locale_id/downloads\" \\\n -u USERNAME_OR_ACCESS_TOKEN \\\n -X POST \\\n -d '{\"branch\":\"my-feature-branch\",\"file_format\":\"yml\",\"tags\":\"feature1,feature\",\"custom_metadata_filters\":{\"tone\":\"friendly\"}}' \\\n -H 'Content-Type: application/json'"
},
{
"lang": "CLI v2",
"source": "phrase locale_downloads create \\\n--project_id <project_id> \\\n--locale_id <locale_id> \\\n--branch my-feature-branch \\\n--file_format yml \\\n--tags feature1,feature2 \\\n--access_token <token>"
}
],
"x-cli-version": "2.29.0"
}
},
"/projects/{project_id}/locales/{locale_id}/downloads/{id}": {
"get": {
"summary": "Show status of an async locale download",
"description": "Show status of already started async locale download. If the download is finished, the download link will be returned.",
"operationId": "locale_download/show",
"tags": [
"Locale Downloads"
],
"parameters": [
{
"$ref": "#/components/parameters/X-PhraseApp-OTP"
},
{
"$ref": "#/components/parameters/If-Modified-Since"
},
{
"$ref": "#/components/parameters/If-None-Match"
},
{
"$ref": "#/components/parameters/project_id"
},
{
"$ref": "#/components/parameters/locale_id"
},
{
"$ref": "#/components/parameters/id"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/locale_download"
}
}
},
"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"
}
}
},
"400": {
"$ref": "#/components/responses/400"
},
"404": {
"$ref": "#/components/responses/404"
},
"429": {
"$ref": "#/components/responses/429"
}
},
"x-code-samples": [
{
"lang": "Curl",
"source": "curl \"https://api.phrase.com/v2/projects/:project_id/locales/:locale_id/downloads/:id\" \\\n -u USERNAME_OR_ACCESS_TOKEN"
},
{
"lang": "CLI v2",
"source": "phrase locale_downloads show \\\n--project_id <project_id> \\\n--locale_id <locale_id> \\\n--id <id>\n--access_token <token>"
}
],
"x-cli-version": "2.29.0"
}
},
"/accounts/{account_id}/distributions": {
"get": {
"summary": "List distributions",
Expand Down
2 changes: 2 additions & 0 deletions main.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -134,7 +134,9 @@ tags:
- name: Job Templates
- name: Jobs
- name: Keys
- name: Linked Keys
- name: Locales
- name: Locale Downloads
- name: Members
description: |
With the members endpoints you can do basic [team and user management](https://support.phrase.com/hc/en-us/articles/5709742418716) 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.
Expand Down
6 changes: 6 additions & 0 deletions paths.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -108,6 +108,12 @@
"/projects/{project_id}/locales/{id}/download":
get:
"$ref": "./paths/locales/download.yaml"
"/projects/{project_id}/locales/{locale_id}/downloads":
post:
"$ref": "./paths/locale_downloads/create.yaml"
"/projects/{project_id}/locales/{locale_id}/downloads/{id}":
get:
"$ref": "./paths/locale_downloads/show.yaml"
"/accounts/{account_id}/distributions":
get:
"$ref": "./paths/distributions/index.yaml"
Expand Down
Loading

0 comments on commit 6fcab5d

Please sign in to comment.