Welcome to collective.restapi.linguaplone’s documentation!¶

https://secure.travis-ci.org/collective/collective.restapi.linguaplone.png?branch=master

https://coveralls.io/repos/github/collective/collective.restapi.linguaplone/badge.svg?branch=master

collective.restapi.linguaplone¶

An add-on providing plone.restapi endpoint for translations handled using LinguaPlone

Documentation¶

Full documentation for end users can be found in the “docs” folder, and is also available online at https://collectiverestapilinguaplone.readthedocs.io

Installation¶

Install collective.restapi.linguaplone by adding it to your buildout:

[buildout]

...

eggs =
    collective.restapi.linguaplone

and then running bin/buildout

Contribute¶

Issue Tracker: https://github.com/collective/collective.restapi.linguaplone/issues
Source Code: https://github.com/collective/collective.restapi.linguaplone
Documentation: https://collectiverestapilinguaplone.readthedocs.io

License¶

The project is licensed under the GPLv2.

Contents¶

LinguaPlone Translations¶

Note

This addon will only work with Products.LinguaPlone in Plone 4. You can install collective.restapi.pam if you want to get similar features in Plone 4 using plone.app.multilingual versions 1.x and 2.x and use plain plone.restapi in Plone 5.

Using this addon you can get information about the translations of a content object handled using Products.LinguaPlone. To achieve that it provides a @translations endpoint to handle the translation information of the content objects.

Once we have installed Products.LinguaPlone and enabled more than one language we can link two content-items of different languages to be the translation of each other issuing a POST query to the @translations endpoint including the id of the content which should be linked to. The id of the content must be a full URL of the content object:

http

POST /plone/en/test-document/@translations HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Content-Type: application/json

{
    "id": "http://localhost:55001/plone/es/test-document"
}

curl

curl -i -X POST http://nohost/plone/en/test-document/@translations -H "Accept: application/json" -H "Content-Type: application/json" --data-raw '{"id": "http://localhost:55001/plone/es/test-document"}' --user admin:secret

httpie

http -j POST http://nohost/plone/en/test-document/@translations id=http://localhost:55001/plone/es/test-document -a admin:secret

python-requests

requests.post('http://nohost/plone/en/test-document/@translations', headers={'Accept': 'application/json'}, json={'id': 'http://localhost:55001/plone/es/test-document'}, auth=('admin', 'secret'))

Note

“id” is a required field and needs to point to an existing content on the site.

The API will return a 201 Created response if the linking was successful.

HTTP/1.1 201 Created
Content-Type: application/json
Location: http://localhost:55001/plone/en/test-document

{}

After linking the contents we can get the list of the translations of that content item by issuing a GET request on the @translations endpoint of that content item.:

http

GET /plone/en/test-document/@translations HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i http://nohost/plone/en/test-document/@translations -H "Accept: application/json" --user admin:secret

httpie

http -j http://nohost/plone/en/test-document/@translations -a admin:secret

python-requests

requests.get('http://nohost/plone/en/test-document/@translations', headers={'Accept': 'application/json'}, auth=('admin', 'secret'))

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@id": "http://localhost:55001/plone/en/test-document/@translations", 
  "items": [
    {
      "@id": "http://localhost:55001/plone/es/test-document", 
      "language": "es"
    }
  ]
}

To unlink the content, issue a DELETE request on the @translations endpoint of the content item and provide the language code you want to unlink.:

http

DELETE /plone/en/test-document/@translations HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Content-Type: application/json

{
    "language": "es"
}

curl

curl -i -X DELETE http://nohost/plone/en/test-document/@translations -H "Accept: application/json" -H "Content-Type: application/json" --data-raw '{"language": "es"}' --user admin:secret

httpie

http -j DELETE http://nohost/plone/en/test-document/@translations language=es -a admin:secret

python-requests

requests.delete('http://nohost/plone/en/test-document/@translations', headers={'Accept': 'application/json'}, json={'language': 'es'}, auth=('admin', 'secret'))

Note

“language” is a required field.

HTTP/1.1 204 No Content

Expansion¶

This endpoint uses the expansion mechanism of plone.restapi which allows to get additional information about a content item in one query, avoiding unnecesary requests.

If a simple GET request is done on the content item, a new entry will be shown on the @components entry with the URL of the @translations endpoint:

http

GET /plone/en/test-document HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i http://nohost/plone/en/test-document -H "Accept: application/json" --user admin:secret

httpie

http -j http://nohost/plone/en/test-document -a admin:secret

python-requests

requests.get('http://nohost/plone/en/test-document', headers={'Accept': 'application/json'}, auth=('admin', 'secret'))

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@components": {
    "breadcrumbs": {
      "@id": "http://localhost:55001/plone/en/test-document/@breadcrumbs"
    }, 
    "navigation": {
      "@id": "http://localhost:55001/plone/en/test-document/@navigation"
    }, 
    "translations": {
      "@id": "http://localhost:55001/plone/en/test-document/@translations"
    }, 
    "workflow": {
      "@id": "http://localhost:55001/plone/en/test-document/@workflow"
    }
  }, 
  "@id": "http://localhost:55001/plone/en/test-document", 
  "@type": "Document", 
  "UID": "SomeUUID000000000000000000000004", 
  "allowDiscussion": false, 
  "contributors": [], 
  "creation_date": "2016-10-21T21:00:00+02:00", 
  "creators": [
    "test_user_1_"
  ], 
  "description": {
    "content-type": "text/plain", 
    "data": ""
  }, 
  "effectiveDate": null, 
  "excludeFromNav": false, 
  "expirationDate": null, 
  "id": "test-document", 
  "is_folderish": false, 
  "language": "en", 
  "layout": "document_view", 
  "location": "", 
  "modification_date": "2016-10-21T21:00:00+02:00", 
  "parent": {
    "@id": "http://localhost:55001/plone/en", 
    "@type": "Folder", 
    "description": "", 
    "review_state": "published", 
    "title": "English"
  }, 
  "presentation": false, 
  "relatedItems": [], 
  "review_state": "private", 
  "rights": {
    "content-type": "text/plain", 
    "data": ""
  }, 
  "subject": [], 
  "tableContents": false, 
  "text": {
    "content-type": "text/plain", 
    "data": ""
  }, 
  "title": "Test document"
}

That means that, to include the translations of the item in the main content response, you can request to expand it:

http

GET /plone/en/test-document?expand=translations HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i 'http://nohost/plone/en/test-document?expand=translations' -H "Accept: application/json" --user admin:secret

httpie

http -j 'http://nohost/plone/en/test-document?expand=translations' -a admin:secret

python-requests

requests.get('http://nohost/plone/en/test-document?expand=translations', headers={'Accept': 'application/json'}, auth=('admin', 'secret'))

And the response will include the required information:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@components": {
    "breadcrumbs": {
      "@id": "http://localhost:55001/plone/en/test-document/@breadcrumbs"
    }, 
    "navigation": {
      "@id": "http://localhost:55001/plone/en/test-document/@navigation"
    }, 
    "translations": {
      "@id": "http://localhost:55001/plone/en/test-document/@translations", 
      "items": [
        {
          "@id": "http://localhost:55001/plone/es/test-document", 
          "language": "es"
        }
      ]
    }, 
    "workflow": {
      "@id": "http://localhost:55001/plone/en/test-document/@workflow"
    }
  }, 
  "@id": "http://localhost:55001/plone/en/test-document", 
  "@type": "Document", 
  "UID": "SomeUUID000000000000000000000004", 
  "allowDiscussion": false, 
  "contributors": [], 
  "creation_date": "2016-10-21T21:00:00+02:00", 
  "creators": [
    "test_user_1_"
  ], 
  "description": {
    "content-type": "text/plain", 
    "data": ""
  }, 
  "effectiveDate": null, 
  "excludeFromNav": false, 
  "expirationDate": null, 
  "id": "test-document", 
  "is_folderish": false, 
  "language": "en", 
  "layout": "document_view", 
  "location": "", 
  "modification_date": "2016-10-21T21:00:00+02:00", 
  "parent": {
    "@id": "http://localhost:55001/plone/en", 
    "@type": "Folder", 
    "description": "", 
    "review_state": "published", 
    "title": "English"
  }, 
  "presentation": false, 
  "relatedItems": [], 
  "review_state": "private", 
  "rights": {
    "content-type": "text/plain", 
    "data": ""
  }, 
  "subject": [], 
  "tableContents": false, 
  "text": {
    "content-type": "text/plain", 
    "data": ""
  }, 
  "title": "Test document"
}

Upgrade guide¶

This upgrade guide lists all breaking changes in collective.restapi.linguaplone and explains the necessary steps that are needed to upgrade to the lastest version.

Upgrading to collective.restapi.linguaplone 2.0.0¶

The JSON response to a GET request to the LinguaPlone Translations endpoint does not include anymore the language of the actual content item.

The JSON response to a GET request to the LinguaPlone Translations endpoint includes the actual translations in an attribute called items instead of translations.

These changes were done to behave like the other existing endpoints that are also expandable, which as top level information only include the name of the endpoint on the id attribute and the actual information in an attribute called items.