Documentation

API

Discussion API

The Discussion API is composed of 4 endpoints:

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.

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/api_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/api_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

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.

js
[
    {
        "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": "CODEBLOCK6quot;service ofCODEBLOCK6quot; -> CODEBLOCK6quot;service byCODEBLOCK6quot;",
                "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": []
            }
        ]
    }
]

Implementation Example in Ruby:

ruby
require 'net/http'
http = Net::HTTP.new('webtranslateit.com', 443)
http.use_ssl = true
request = Net::HTTP::Post.new('/api/projects/:api_token/discussions.json')
response = http.request(request)

Implementation Example in PHP:

php
<?php
  $api_key = "sekret";
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, "https://webtranslateit.com/api/projects/" . $api_key . "/discussions.json");
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  $response = curl_exec($ch);
  print_r($response);
  curl_close($ch);
?>

Delete Discussion

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

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

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

Implementation Example in Ruby:

ruby
require 'net/http'
http = Net::HTTP.new('webtranslateit.com', 443)
http.use_ssl = true
request = Net::HTTP::Delete.new('/api/projects/:api_token/discussion/:discussion_id')
response = http.request(request)

Implementation Example in PHP:

php
<?php
  $api_key = "sekret";
  $discussion_id_ = 123;
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, "https://webtranslateit.com/api/projects/" . $api_key . "/discussion/" . $discussion_id);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
  $response = curl_exec($ch);
  print_r($response);
  curl_close($ch);
?>

Lock Discussion

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

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

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

Unlock Discussion

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

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

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