API

Discussion API

List, delete, lock and unlock the discussions attached to translation segments with the WebTranslateIt Discussion API. 7 min read

The Discussion API is composed of 4 endpoints:

List Discussions — list the discussions and attached comments on a project
Delete Discussion — delete a discussion
Lock Discussion - lock a discussion
Unlock Discussion - unlock a discussion

List Discussions

This endpoint is accessible by both read-write and read-only Project API keys and returns the discussions on a project.

/api/projects/:project_token/discussions [GET]

Pagination

This resource is paginated and serves 250 Discussions per page. You can specify further page using the ?page parameter. Note that page numbering is 1-based and that omitting the ?page parameter will return the first page.

Link Header

The pagination information is included in the Link header. You can use the Link Header in order to know which page is next and which page is the last one, instead of constructing your own URLs.

For instance, let’s make a curl request to the TermBase API:

bash

curl -I "https://webtranslateit.com/api/projects/PROJECT_TOKEN/discussions.json"

The -I parameter indicates that we only care about the headers, not the actual content. In examining the result, you’ll notice some information in the Link header that looks like this:

Link: <https://webtranslateit.com/api/projects/api_key/discussions.json?page=2>; rel="next",
  <https://webtranslateit.com/api/projects/api_key/discussions.json?page=20>; rel="last"

The possible rel values are:

next: Shows the URL of the immediate next page of results.
last: Shows the URL of the last page of results.
first: Shows the URL of the first page of results.
prev: Shows the URL of the immediate previous page of results.

Here’s another example of the Link Header when browsing the 3rd page:

bash

curl -I "https://webtranslateit.com/api/projects/PROJECT_TOKEN/discussions.json?page=3"

Link: <https://webtranslateit.com/api/projects/api_key/discussions.json?page=4>; rel="next",
  <https://webtranslateit.com/api/projects/api_key/discussions.json?page=9>; rel="last",
  <https://webtranslateit.com/api/projects/api_key/discussions.json?page=1>; rel="first",
  <https://webtranslateit.com/api/projects/api_key/discussions.json?page=2>; rel="prev"

This resource is paginated and serves 250 Discussions per page. In the server response headers, you will find Link, with a link for an API call to the next and last pages.

Optional Parameters:

string_id: ID of a segment
locale: the locale of the discussion: en-US, en_GB or fr for instance.
kind: can be segments to list discussions about segments only or project to list discussions about projects only.
status: can be locked or left blank.
page: the page number

GET/api/projects/:project_token/discussions.json

curl "https://webtranslateit.com/api/projects/PROJECT_TOKEN/discussions.json?kind=segments"

const response = await fetch(
  'https://webtranslateit.com/api/projects/PROJECT_TOKEN/discussions.json?kind=segments'
)
const discussions = await response.json()

import requests

response = requests.get(
    "https://webtranslateit.com/api/projects/PROJECT_TOKEN/discussions.json",
    params={"kind": "segments"},
)
discussions = response.json()

require 'net/http'
require 'json'

uri = URI('https://webtranslateit.com/api/projects/PROJECT_TOKEN/discussions.json')
uri.query = URI.encode_www_form(kind: 'segments')
discussions = JSON.parse(Net::HTTP.get(uri))

<?php
$ch = curl_init('https://webtranslateit.com/api/projects/PROJECT_TOKEN/discussions.json?kind=segments');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$discussions = json_decode(curl_exec($ch), true);
curl_close($ch);

Example query:

https://webtranslateit.com/api/projects/api_key/discussions.json

Example response with JSON:

The author’s e-mail address is anonymized when authenticating using the read-only API token. E-mail address is visible when authenticating using the read-write API token.

[
    {
        "id": 35609,
        "kind": "project",
        "resource_id": 406,
        "created_at": "2014-07-04T09:30:07Z",
        "updated_at": "2014-07-04T09:30:07Z",
        "author": {
            "name": "Édouard Brière",
            "email": ""
        },
        "last_author": {
            "name": "Édouard Brière",
            "email": ""
        },
        "topic": "A discussion with attachments",
        "status": "open",
        "comments": [
            {
                "id": 83636,
                "created_at": "2014-07-04T09:30:07Z",
                "author": {
                    "name": "Édouard Brière",
                    "email": ""
                },
                "text": "This is comment 1",
                "file_attachments": [
                    {
                        "id": 5636,
                        "created_at": "2014-07-04T09:30:01Z",
                        "url": "https://s3.amazonaws.com/users0-webtranslateit/development/file_attachments/original/5636_c56d2833ca71dedd18c200e545136e2589310fdd.png?1404466201"
                    }
                ]
            },
            {
                "id": 83637,
                "created_at": "2014-07-04T09:30:20Z",
                "author": {
                    "name": "Édouard Brière",
                    "email": ""
                },
                "text": "Comment 2",
                "file_attachments": []
            }
        ]
    },
    {
        "id": 15577,
        "kind": "segment",
        "resource_id": 772340,
        "created_at": "2012-02-14T11:43:11Z",
        "updated_at": "2012-03-09T08:35:56Z",
        "author": {
            "name": "Estelle Alexandre",
            "email": ""
        },
        "last_author": {
            "name": "Estelle Alexandre",
            "email": ""
        },
        "topic": null,
        "status": "open",
        "comments": [
            {
                "id": 42420,
                "created_at": "2012-02-14T11:43:11Z",
                "author": {
                    "name": "Estelle Alexandre",
                    "email": ""
                },
                "text": "\"service of\" -> \"service by\"",
                "file_attachments": []
            },
            {
                "id": 43260,
                "created_at": "2012-03-09T08:36:22Z",
                "author": {
                    "name": "Édouard Brière",
                    "email": ""
                },
                "text": "Thanks!",
                "file_attachments": []
            }
        ]
    },
    {
        "id": 12276,
        "kind": "segment",
        "resource_id": 772344,
        "created_at": "2011-06-20T15:28:18Z",
        "updated_at": "2011-06-20T15:28:18Z",
        "author": {
            "name": "Stina Oskarsson",
            "email": ""
        },
        "last_author": {
            "name": "Stina Oskarsson",
            "email": ""
        },
        "topic": null,
        "status": "open",
        "comments": [
            {
                "id": 36204,
                "created_at": "2011-06-20T15:28:18Z",
                "author": {
                    "name": "Stina Oskarsson",
                    "email": ""
                },
                "text": "developed (here: developped) is spelled with one P.",
                "file_attachments": []
            }
        ]
    },
    {
        "id": 680,
        "kind": "segment",
        "resource_id": 140435,
        "created_at": "2010-02-26T20:02:24Z",
        "updated_at": "2010-02-26T20:12:10Z",
        "author": {
            "name": "Alex Soulim",
            "email": ""
        },
        "last_author": {
            "name": "Alex Soulim",
            "email": ""
        },
        "topic": null,
        "status": "open",
        "comments": [
            {
                "id": 10036,
                "created_at": "2010-02-26T20:02:24Z",
                "author": {
                    "name": "Alex Soulim",
                    "email": ""
                },
                "text": "There are some strange symbols in this string (when you try to edit it).\nIs it ok?",
                "file_attachments": []
            },
            {
                "id": 10038,
                "created_at": "2010-02-26T20:07:06Z",
                "author": {
                    "name": "Édouard Brière",
                    "email": ""
                },
                "text": "Thanks for spotting this, there is a problem indeed. The Russian string is plural whereas the English string is not. Will fix!",
                "file_attachments": []
            },
            {
                "id": 10039,
                "created_at": "2010-02-26T20:12:10Z",
                "author": {
                    "name": "Édouard Brière",
                    "email": ""
                },
                "text": "There, it’s fixed!",
                "file_attachments": []
            }
        ]
    },
    {
        "id": 669,
        "kind": "segment",
        "resource_id": 140483,
        "created_at": "2010-02-12T20:43:33Z",
        "updated_at": "2010-02-12T20:43:33Z",
        "author": {
            "name": "Édouard Brière",
            "email": ""
        },
        "last_author": {
            "name": "Édouard Brière",
            "email": ""
        },
        "topic": null,
        "status": "open",
        "comments": [
            {
                "id": 9949,
                "created_at": "2010-02-12T20:43:33Z",
                "author": {
                    "name": "Édouard Brière",
                    "email": ""
                },
                "text": "Don’t translate this",
                "file_attachments": []
            }
        ]
    }
]

Delete Discussion

This endpoint is accessible by the read-write Project API key and deletes a discussion on a project.

/api/projects/:project_token/discussions/:discussion_id [DELETE]

If everything goes well, the server should respond with 202 Accepted in the response headers.

DELETE/api/projects/:project_token/discussions/:discussion_id

curl -X DELETE "https://webtranslateit.com/api/projects/PROJECT_TOKEN/discussions/123"

await fetch(
  'https://webtranslateit.com/api/projects/PROJECT_TOKEN/discussions/123',
  { method: 'DELETE' }
)

import requests

requests.delete(
    "https://webtranslateit.com/api/projects/PROJECT_TOKEN/discussions/123"
)

require 'net/http'

uri = URI('https://webtranslateit.com/api/projects/PROJECT_TOKEN/discussions/123')
Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
  http.request(Net::HTTP::Delete.new(uri))
end

<?php
$ch = curl_init('https://webtranslateit.com/api/projects/PROJECT_TOKEN/discussions/123');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_exec($ch);
curl_close($ch);

Lock Discussion

This endpoint is accessible by the read-write Project API key and locks a discussion on a project, so no further comments can be added.

/api/projects/:project_token/discussions/:discussion_id/lock [PATCH]

If everything goes well, the server should respond with 202 Accepted in the response headers.

PATCH/api/projects/:project_token/discussions/:discussion_id/lock

curl -X PATCH "https://webtranslateit.com/api/projects/PROJECT_TOKEN/discussions/123/lock"

await fetch(
  'https://webtranslateit.com/api/projects/PROJECT_TOKEN/discussions/123/lock',
  { method: 'PATCH' }
)

import requests

requests.patch(
    "https://webtranslateit.com/api/projects/PROJECT_TOKEN/discussions/123/lock"
)

require 'net/http'

uri = URI('https://webtranslateit.com/api/projects/PROJECT_TOKEN/discussions/123/lock')
Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
  http.request(Net::HTTP::Patch.new(uri))
end

<?php
$ch = curl_init('https://webtranslateit.com/api/projects/PROJECT_TOKEN/discussions/123/lock');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_exec($ch);
curl_close($ch);

Unlock Discussion

This endpoint is accessible by the read-write Project API key and unlocks a previously locked discussion, so comments can be added again.

/api/projects/:project_token/discussions/:discussion_id/unlock [PATCH]

If everything goes well, the server should respond with 202 Accepted in the response headers.

PATCH/api/projects/:project_token/discussions/:discussion_id/unlock

curl -X PATCH "https://webtranslateit.com/api/projects/PROJECT_TOKEN/discussions/123/unlock"

await fetch(
  'https://webtranslateit.com/api/projects/PROJECT_TOKEN/discussions/123/unlock',
  { method: 'PATCH' }
)

import requests

requests.patch(
    "https://webtranslateit.com/api/projects/PROJECT_TOKEN/discussions/123/unlock"
)

require 'net/http'

uri = URI('https://webtranslateit.com/api/projects/PROJECT_TOKEN/discussions/123/unlock')
Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
  http.request(Net::HTTP::Patch.new(uri))
end

<?php
$ch = curl_init('https://webtranslateit.com/api/projects/PROJECT_TOKEN/discussions/123/unlock');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_exec($ch);
curl_close($ch);

Documentation

Discussion API

List Discussions#

Pagination#

Link Header#

Optional Parameters:#

Example query:#

Example response with JSON:#

Delete Discussion#

Lock Discussion#

Unlock Discussion#

List Discussions

Pagination

Link Header

Optional Parameters:

Example query:

Example response with JSON:

Delete Discussion

Lock Discussion

Unlock Discussion