From 26bd75f08ed092699950b980047bc30c6feea69f Mon Sep 17 00:00:00 2001 From: kusztel Date: Tue, 25 Jul 2017 10:30:47 +0200 Subject: [PATCH 1/3] EZP-27653 - Clean manually the md files and merge files if needed Api and getting started --- docs/api/api.md | 7 +- docs/api/extending_the_rest_api.md | 42 ++-- docs/api/field_type_api_and_best_practices.md | 80 ++----- docs/api/general_rest_usage.md | 46 ++-- docs/api/js_client.md | 22 +- docs/api/public_php_api.md | 146 ++++++------- docs/api/rest_api_guide.md | 26 +-- docs/api/rest_api_reference.md | 22 +- docs/getting_started/about_composer.md | 203 +++++------------- docs/getting_started/ez_enterprise.md | 18 +- docs/getting_started/ez_platform_features.md | 26 +-- .../get_started_with_ez_platform.md | 17 +- docs/getting_started/img/Landing_Page.png | Bin 0 -> 1597 bytes .../img/Using_Composer_Auth_token.png | Bin 0 -> 18118 bytes docs/getting_started/img/edit_icon.png | Bin 0 -> 1422 bytes docs/getting_started/img/flex_icon.png | Bin 0 -> 2559 bytes .../img/ibex_mountain_small.png | Bin 0 -> 37720 bytes docs/getting_started/img/schedule.png | Bin 0 -> 1461 bytes docs/getting_started/install_ez_platform.md | 79 +------ docs/getting_started/install_manually.md | 179 ++++++++------- .../getting_started/install_using_composer.md | 23 +- docs/getting_started/install_using_docker.md | 48 ----- .../requirements_and_system_configuration.md | 38 +--- docs/getting_started/starting_ez_platform.md | 132 +++--------- docs/getting_started/troubleshooting.md | 15 +- 25 files changed, 336 insertions(+), 833 deletions(-) create mode 100644 docs/getting_started/img/Landing_Page.png create mode 100644 docs/getting_started/img/Using_Composer_Auth_token.png create mode 100644 docs/getting_started/img/edit_icon.png create mode 100644 docs/getting_started/img/flex_icon.png create mode 100644 docs/getting_started/img/ibex_mountain_small.png create mode 100644 docs/getting_started/img/schedule.png delete mode 100644 docs/getting_started/install_using_docker.md diff --git a/docs/api/api.md b/docs/api/api.md index 93a4cd3c29..53c244afa5 100644 --- a/docs/api/api.md +++ b/docs/api/api.md @@ -1,11 +1,10 @@ -1. [Developer](index.html) -2. [Documentation](Documentation_31429504.html) + # API An Application Programming Interface (API) allows you to connect your code to eZ Platform. -From the eZ Blog:  +From the eZ Blog: [How would you explain what an API is to your mom](http://ez.no/Blog/How-would-you-explain-what-an-API-is-to-your-mom) eZ Platform offers two APIs: @@ -13,5 +12,3 @@ eZ Platform offers two APIs: 2. The [Public (PHP) API](https://doc.ez.no/display/DEVELOPER/Public+API+Guide) exposes a Repository which allows you to create, read, update, manage and delete all objects available in eZ Platform, first and foremost content, but also related objects like sections, locations, content types, content types groups, languages and so on. There is also a [JavaScript API Client](JS-Client_31429579.html), useful for working with eZ Platform as a [headless CMS](http://ez.no/Blog/Content-as-a-Service-CaaS-Decoupled-CMS-and-Headless-CMS-101). - -  diff --git a/docs/api/extending_the_rest_api.md b/docs/api/extending_the_rest_api.md index 781fed3365..5cde34b0d3 100644 --- a/docs/api/extending_the_rest_api.md +++ b/docs/api/extending_the_rest_api.md @@ -1,7 +1,4 @@ -1. [Developer](index.html) -2. [Documentation](Documentation_31429504.html) -3. [API](API_31429524.html) -4. [REST API Guide](REST-API-Guide_31430286.html) + # Extending the REST API @@ -27,7 +24,7 @@ Let's create a very simple controller, that has a `sayHello()` method, that take **My/Bundle/RestBundle/Rest/Controller/DefaultController.php** -``` brush: +``` php: namespace My\Bundle\RestBundle\Rest\Controller;   use eZ\Publish\Core\REST\Server\Controller as BaseController; @@ -47,7 +44,7 @@ As said earlier, your REST routes are required to use the REST URI prefix. To do **app/config/routing.yml** -``` brush: +``` yaml: myRestBundle_rest_routes: resource: "@MyRestBundle/Resources/config/routing_rest.yml" prefix: %ezpublish_rest.path_prefix% @@ -59,7 +56,7 @@ Next, you need to create the REST route. We need to define the route's [controll **My/Bundle/RestBundle/Resources/config/routing\_rest.yml** -``` brush: +``` yaml: myRestBundle_hello_world: pattern: /my_rest_bundle/hello/{name} defaults: @@ -77,7 +74,7 @@ Let's say that our Controller will return a `My\Bundle\RestBundle\Rest\Values\He **My/Bundle/RestBundle/Rest/Values/Hello.php** -``` brush: +``` php: namespace My\Bundle\RestBundle\Rest\Values;   class Hello @@ -95,7 +92,7 @@ We will return an instance of this class from our `sayHello()` controller method **My/Bundle/RestBundle/Rest/Controller/DefaultController.php** -``` brush: +``` php: namespace My\Bundle\RestBundle\Controller; use eZ\Publish\Core\REST\Server\Controller as BaseController; @@ -120,7 +117,7 @@ Let's create the service for our ValueObjectVisitor first. **My/Bundle/RestBundle/Resources/config/services.yml** -``` brush: +``` yaml: services: myRestBundle.value_object_visitor.hello: parent: ezpublish_rest.output.value_object_visitor.base @@ -138,7 +135,7 @@ It will receive as arguments: **My/Bundle/RestBundle/Rest/Controller/Default.php** -``` brush: +``` php: namespace My\Bundle\RestBundle\Rest\ValueObjectVisitor; use eZ\Publish\Core\REST\Common\Output\ValueObjectVisitor; @@ -163,7 +160,7 @@ The easiest way to handle cache is to re-use the ` CachedValue When you want the response to be cached, return an instance of CachedValue, with your Value Object as the argument. You can also pass a location id using the second argument, so that the Response is tagged with it: -``` brush: +``` return new CachedValue($helloValue, ['locationId', 42]); ``` @@ -179,7 +176,7 @@ Let's see what it would look like with a Content-Type of application/vnd.my.Gree **application/vnd.my.Greetings+xml** -``` brush: +``` xml: John doe @@ -190,7 +187,7 @@ First, we need to create a service with the appropriate tag in services.yml. **My/Bundle/RestBundle/Resources/config/services.yml** -``` brush: +``` yaml: services: myRestBundle.input_parser.Greetings: parent: ezpublish_rest.input.parser @@ -207,7 +204,7 @@ For convenience, we will consider that our input parser returns an instance of o **My/Bundle/RestBundle/Rest/InputParser/Greetings.php** -``` brush: +``` php: namespace My\Bundle\RestBundle\Rest\InputParser;   use eZ\Publish\Core\REST\Common\Input\BaseParser; @@ -235,7 +232,7 @@ class Greetings extends BaseParser **My/Bundle/RestBundle/Resources/config/services.yml** -``` brush: +``` yaml: services: myRestBundle.controller.default: class: My\Bundle\RestBundle\Rest\Controller\Default @@ -252,7 +249,7 @@ You can register newly added resources so that they show up in the REST root res New resources can be registered with code like this: -``` brush: +``` ez_publish_rest: system: default: @@ -275,14 +272,3 @@ This syntax is based on [Symfony's expression language](http://symfony.com/doc/c The above configuration will add the following entry to the root resource: `` - -#### In this topic: - -- [Requirements](#ExtendingtheRESTAPI-Requirements) - - [Controller](#ExtendingtheRESTAPI-Controller) - - [Route](#ExtendingtheRESTAPI-Route) -- [Controller action](#ExtendingtheRESTAPI-Controlleraction) -- [ValueObjectVisitor](#ExtendingtheRESTAPI-ValueObjectVisitor) - - [Cache handling](#ExtendingtheRESTAPI-Cachehandling) -- [Input parser](#ExtendingtheRESTAPI-Inputparser) -- [Registering resources in the REST root](#ExtendingtheRESTAPI-RegisteringresourcesintheRESTroot) diff --git a/docs/api/field_type_api_and_best_practices.md b/docs/api/field_type_api_and_best_practices.md index 1e0b312dda..f0251f1af7 100644 --- a/docs/api/field_type_api_and_best_practices.md +++ b/docs/api/field_type_api_and_best_practices.md @@ -1,10 +1,7 @@ -1. [Developer](index.html) -2. [Documentation](Documentation_31429504.html) -3. [API](API_31429524.html) + # Field Type API and best practices -Created by Dominika Kurek, last modified by Michał Maciej Kusztelak on May 08, 2017 # Field Type API & best practices @@ -71,7 +68,7 @@ Otherwise the regular `{FieldType}->getName()` method is used. **Example from fieldtype\_services.yml** -``` brush: +``` yaml: # Nameable services (for fieldtypes that need advance name handling) ezpublish.fieldType.ezobjectrelation.nameable_field: class: %ezpublish.fieldType.ezobjectrelation.nameable_field.class% @@ -149,7 +146,7 @@ This method is supposed to return the actual index data for the provided `eZ\Pub To be able to query data properly an indexable field type also is required to return search specification. You must return a hash map of `eZ\Publish\SPI\Persistence\Content\Search\FieldType` instances from this method, which could look like: -``` brush: +``` array( 'url'  => new Search\FieldType\StringField(),     'text' => new Search\FieldType\StringField(), @@ -224,7 +221,7 @@ If you want to configure the handling of your field, you can always add a specia You could also define a custom field definition dedicatedly for certain fields, like for the name field in an article: -``` brush: +``` ``` @@ -391,7 +388,7 @@ It is recommended to use a simple hash map format for the settings schema reture An example schema could look like this: -``` brush: +``` array( 'backupData' => array( 'type' => 'bool', @@ -418,7 +415,7 @@ The schema for validator configuration should have a similar format than the set For example, for the `ezstring` type, the validator schema could be: -``` brush: +``` array( 'stringLength' => array( 'minStringLength' => array( @@ -466,7 +463,7 @@ The integration tests with the Persistence SPI can be found in `eZ\Publish\SPI\T Running the test is fairly simple: Just specify the global `phpunit.xml` for PHPUnit configuration and make it execute a single test or a directory of tests, for example: -``` brush: +``` bash: $ phpunit -c phpunit.xml eZ/Publish/SPI/Tests/FieldType ``` @@ -482,50 +479,12 @@ Note that the In-Memory stubs for the Public API integration test suite, do not If your Field Type needs to convert data between `storeFieldData()` and `getFieldData()`, you need to implement a `eZ\Publish\API\Repository\Tests\Stubs\PseudoExternalStorage` in addition, which performs this task. Running the tests against the Business Layer implementation of the Public API is not affected by this. -  - -  +## Field Type template -#### In this topic: - -- [Field Type API & best practices](#FieldTypeAPIandbestpractices-FieldTypeAPI&bestpractices) - - [Public API interaction](#FieldTypeAPIandbestpractices-PublicAPIinteraction) - - [FieldDefinition handling](#FieldTypeAPIandbestpractices-FieldDefinitionhandling) - - [Value handling](#FieldTypeAPIandbestpractices-Valuehandling) - - [Storage conversion](#FieldTypeAPIandbestpractices-Storageconversion) - - [Searching](#FieldTypeAPIandbestpractices-Searching) - - [Search Field Values](#FieldTypeAPIandbestpractices-SearchFieldValues) - - [Search Field Types](#FieldTypeAPIandbestpractices-SearchFieldTypes) - - [Configuring Solr](#FieldTypeAPIandbestpractices-ConfiguringSolr) - - [Storing external data](#FieldTypeAPIandbestpractices-Storingexternaldata) - - [Legacy Storage conversion](#FieldTypeAPIandbestpractices-LegacyStorageconversion) - - [Registering a converter](#FieldTypeAPIandbestpractices-Registeringaconverter) - - [REST API interaction](#FieldTypeAPIandbestpractices-RESTAPIinteraction) - - [Extension points](#FieldTypeAPIandbestpractices-Extensionpoints) - - [Best practices](#FieldTypeAPIandbestpractices-Bestpractices) - - [Gateway based Storage](#FieldTypeAPIandbestpractices-GatewaybasedStorage) - - [Settings schema](#FieldTypeAPIandbestpractices-Settingsschema) - - [Validator schema](#FieldTypeAPIandbestpractices-Validatorschema) - - [Registering a Field Type](#FieldTypeAPIandbestpractices-RegisteringaFieldType) - - [Templating](#FieldTypeAPIandbestpractices-Templating) - - [Testing](#FieldTypeAPIandbestpractices-Testing) - - [Persistence SPI](#FieldTypeAPIandbestpractices-PersistenceSPI) - - [Public API](#FieldTypeAPIandbestpractices-PublicAPI) - -## Attachments: - -![](images/icons/bullet_blue.gif) [create\_content\_sequence.png](attachments/31430767/31430764.png) (image/png) -![](images/icons/bullet_blue.gif) [create\_content\_sequence.svg](attachments/31430767/31430765.svg) (image/svg+xml) -![](images/icons/bullet_blue.gif) [field\_type\_overview.png](attachments/31430767/31430766.png) (image/png) - - -# Field Type template - -Created by Dominika Kurek, last modified by David Christian Liedle on May 04, 2017 - -# Defining your Field Type template + +## Defining your Field Type template In order to be used by [`ez_render_field()` Twig helper](ez_render_field_32114041.html), you need to define a **template containing a block** dedicated to the Field display. @@ -535,7 +494,7 @@ You will find examples with built-in Field Types in [EzPublishCoreBundle/Resourc **Template for a FieldType with "myfieldtype" identifier** -``` brush: +``` {% block myfieldtype_field %} {# Your code here #} {% endblock %} @@ -606,7 +565,7 @@ To make your template available, you must register it to the system. **app/config/ezplatform.yml** -``` brush: +``` yaml: ezpublish: system: my_siteaccess: @@ -622,8 +581,6 @@ You can define these rules in a dedicated file instead of `app/config/ezplatform # Register Field Type -Created by Dominika Kurek, last modified on Jul 06, 2017 - # Introduction This document explains how to register a custom Field Type in eZ Platform. It will not contain the development part as it is already covered [in the API section](Field-Type-API-and-best-practices_31430767.html). @@ -642,7 +599,7 @@ This part relates to the [base FieldType class that interacts with the Publish A Let's take a basic example from `ezstring` configuration. -``` brush: +``` parameters: ezpublish.fieldType.ezstring.class: eZ\Publish\Core\FieldType\TextLine\Type   @@ -676,7 +633,7 @@ Those converters also need to be correctly exposed as services. **Field Type converter for ezstring** -``` brush: +``` parameters: ezpublish.fieldType.ezstring.converter.class: eZ\Publish\Core\Persistence\Legacy\Content\FieldValue\Converter\TextLine   @@ -731,7 +688,7 @@ Here is an example for **ezurl** field type: **External storage handler for ezurl** -``` brush: +``` parameters: ezpublish.fieldType.ezurl.externalStorage.class: eZ\Publish\Core\FieldType\Url\UrlStorage   @@ -752,7 +709,7 @@ As stated in the [Field Type best practices](Field-Type-API-and-best-practices_3 **Storage gateway for ezurl** -``` brush: +``` parameters: ezpublish.fieldType.ezurl.storage_gateway.class: eZ\Publish\Core\FieldType\Url\UrlStorage\Gateway\LegacyStorage   @@ -791,11 +748,10 @@ The gateway configuration for basic field types are located in [EzPublishCoreBun -# Settings schema and allowed validators +## Settings schema and allowed validators -Created by Dominika Kurek, last modified on Apr 22, 2016 -# Internal Field Type conventions and best practices +## Internal Field Type conventions and best practices FieldType->$settingsSchema and FieldType->$allowedValidators are intentionally left free-form, to give broadest freedom to Field Type developers. However, for internal Field Types (aka those delivered with eZ Platform), a common standard should be established as best practice. The purpose of this page is to collect and unify this standard. diff --git a/docs/api/general_rest_usage.md b/docs/api/general_rest_usage.md index 13a7474794..508f9a6d6c 100644 --- a/docs/api/general_rest_usage.md +++ b/docs/api/general_rest_usage.md @@ -1,11 +1,7 @@ -1. [Developer](index.html) -2. [Documentation](Documentation_31429504.html) -3. [API](API_31429524.html) -4. [REST API Guide](REST-API-Guide_31430286.html) + # General REST usage -Created by Dominika Kurek, last modified on Apr 22, 2016 As explained in the [introduction](REST-API-Guide_31430286.html), the REST API is based on a very limited list of general principles: @@ -25,7 +21,7 @@ The only requirement for this verb is usually the resource URI, and the accept h **Load ContentInfo request** -``` brush: +``` GET /content/objects/23 HTTP/1.1 Accept: application/vnd.ez.api.ContentInfo+xml ``` @@ -40,7 +36,7 @@ The API will reply with: **Load ContentInfo response** -``` brush: +``` HTTP/1.1 200 OK Accept-Patch: application/vnd.ez.api.ContentUpdate+xml;charset=utf8 Content-Type: application/vnd.ez.api.ContentInfo+xml @@ -83,7 +79,7 @@ This request header is the request counterpart of the Location response header. **Load ContentInfo response body**  Expand source -``` brush: +``` xml: @@ -132,7 +128,7 @@ URI parameters are of course also used. They usually serve as filters / options **GET request with limit parameter** -``` brush: +``` GET /content/objects/59/versions/2/relations&limit=5 HTTP/1.1 Accept: application/vnd.ez.api.RelationList+xml ``` @@ -147,7 +143,7 @@ In addition to the usual GET, POST, PUT and DELETE HTTP verbs, the API supports **PATCH HTTP request** -``` brush: +``` POST /content/objects/59 HTTP/1.1 X-HTTP-Method-Override: PATCH ``` @@ -164,7 +160,7 @@ Due to this, we decided not to enable siteaccess matching with REST. In order to **X-Siteaccess header example** -``` brush: +``` GET / HTTP/1.1 Host: api.example.com Accept: application/vnd.ez.api.Root+json @@ -173,19 +169,10 @@ X-Siteaccess: ezdemo_site_admin   -#### In this topic: - -- [Anatomy of a REST call](#GeneralRESTusage-AnatomyofaRESTcall) - - [What we can learn from a GET request](#GeneralRESTusage-WhatwecanlearnfromaGETrequest) -- [Request parameters](#GeneralRESTusage-Requestparameters) -- [Custom HTTP verbs](#GeneralRESTusage-CustomHTTPverbs) -- [Specifying a siteaccess](#GeneralRESTusage-Specifyingasiteaccess) - # REST API Authentication -Created by Dominika Kurek, last modified on Apr 22, 2016 The REST API supports two authentication methods: session, and basic.  @@ -214,7 +201,7 @@ To enable HTTP Basic authentication, you need to edit app`/config/security.yml`, **ezplatform.yml** -``` brush: +``` yaml: ezpublish_rest: pattern: ^/api/ezp/v2 stateless: true @@ -228,16 +215,14 @@ Most HTTP client libraries as well as REST libraries do support this method one **Raw HTTP request with basic authentication** -``` brush: +``` GET / HTTP/1.1 Host: api.example.com Accept: application/vnd.ez.api.Root+json Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== ``` -# Error handling - -Created by Dominika Kurek, last modified on Apr 22, 2016 +## Error handling Error handling in the REST API is fully based on HTTP error codes. As a web developer, you are probably familiar with the most common ones: 401 Unauthorized, 404 Not Found or 500 Internal Server Error. The REST API uses those, along with a few more, to allow proper error handling. @@ -271,9 +256,8 @@ Returned when an accept header sent with the requested isn't supported. It is up to you, in your client implementation, to handle those codes by checking if an error code (4xx or 5xx) was returned instead of the expected 2xx or 3xx. -# REST API Countries list +## REST API Countries list -Created by Dominika Kurek, last modified on Apr 22, 2016 Countries list is a REST service that gives access to an [ISO-3166](http://en.wikipedia.org/wiki/ISO_3166) formatted list of world countries. It is useful when presenting a country options list from any application. @@ -283,7 +267,7 @@ To send a GET request to the REST API Countries list, you have to provide the Co **Countries list request** -``` brush: +``` Resource: /api/ezp/v2/services/countries Method: GET Content-Type: application/vnd.ez.api.CountriesList+xml @@ -297,7 +281,7 @@ See the [General REST usage documentation page](General-REST-usage_31430291.html **Countries list request** -``` brush: +``` GET /api/ezp/v2/services/countries Host: example.com Accept: application/vnd.ez.api.CountriesList+xml @@ -309,7 +293,7 @@ The HTTP response will it be with a 200 OK Header. **Countries list response headers** -``` brush: +``` HTTP/1.1 200 Content-Type: application/vnd.ez.api.CountriesList+xml ``` @@ -327,7 +311,7 @@ See [the ISO-3166 glossary](http://www.iso.org/iso/home/standards/country_codes/ **Body XML Response** -``` brush: +``` xml: Afghanistan @@ -37,7 +33,7 @@ Alternatively, the JavaScript REST Client can be installed directly in any proje **Installing with bower** -``` brush: +``` php: $ bower install --save ezsystems/ez-js-rest-client ``` @@ -77,7 +73,7 @@ The Session Auth Agent expects an object describing the existing Session or cont **Session Authentication (new session)** -``` brush: +``` php: var capi, credentials = { login: 'admin', @@ -103,7 +99,7 @@ If the user already has a session, the agent expects an object describing the se **Session Authentication (existing session)** -``` brush: +``` : var capi, sessionInfo = { name: 'eZSESSID', // name of the session, might also be something like eZSESSID98defd6ee70dfb1dea416cecdf391f58 @@ -131,7 +127,7 @@ When configured in the Basic Authentication, the basic auth agent just expects t **Basic Authentication** -``` brush: +``` php: var capi, credentials = { login: 'admin', @@ -157,7 +153,7 @@ To load a ContentInfo, you need [the Content Service](http://ezsystems.github.io **Loading a ContentInfo** -``` brush: +``` php: var capi, contentService, contentRestId = '/api/ezp/v2/content/objects/1', credentials = { @@ -188,7 +184,7 @@ To move a Location, [the Content Service](http://ezsystems.github.io/javascript- **Moving a Location** -``` brush: +``` php: var capi, contentService, locationRestId = '/api/ezp/v2/content/locations/1/43/53', // Media/Multimedia in a default install newParentLocationRestId = '/api/ezp/v2/content/locations/1/43/52', // Media/Files in a default install @@ -217,7 +213,7 @@ Searching for Content or Location can be done with [REST views](https://github.c **REST views** -``` brush: +``` php: var capi, contentService, query,  credentials = { login: 'admin', diff --git a/docs/api/public_php_api.md b/docs/api/public_php_api.md index 15d8df5b35..a1e9c3dcb1 100644 --- a/docs/api/public_php_api.md +++ b/docs/api/public_php_api.md @@ -1,10 +1,7 @@ -1. [Developer](index.html) -2. [Documentation](Documentation_31429504.html) -3. [API](API_31429524.html) + # eZ Platform Public PHP API -Created by Dominika Kurek, last modified on Apr 22, 2016 The PHP API is also commonly referred to as the "*Public API*". Currently it exposes a Repository which allows you to create, read, update, manage and delete all objects available in eZ Platform, first and foremost content, but also related objects like Sections, Locations, Content Types, Content Type groups, languages and so on. @@ -16,7 +13,7 @@ It will allow you to create, retrieve, update and delete all the eZ Platform obj **Obtaining the eZ Platform Repository via the service container** -``` brush: +``` php: /** @var $repository \eZ\Publish\API\Repository\Repository $repository = $container->get( 'ezpublish.api.repository' ); ``` @@ -69,19 +66,10 @@ In order to update or create elements in the Repository, you will use structs. T Using them is also covered in the Cookbook. -#### In this topic: - -- [eZ Platform API Repository](#eZPlatformPublicPHPAPI-eZPlatformAPIRepository) -- [The service container](#eZPlatformPublicPHPAPI-Theservicecontainer) -- [Authentication](#eZPlatformPublicPHPAPI-Authentication) -- [Services](#eZPlatformPublicPHPAPI-Services) -- [Value objects](#eZPlatformPublicPHPAPI-Valueobjects) -- [Create and update structs](#eZPlatformPublicPHPAPI-Createandupdatestructs) # Public API Guide -Created by Dominika Kurek, last modified by Sarah Haïm-Lubczanski on Jun 30, 2016 The public API will give you an easy access to the eZ Platform content repository. This repository is the core component that manages content, Locations, Sections, Content Types, Users, User groups, and Roles. It also provides a new, clear interface for plugging in custom Field Types. @@ -114,7 +102,7 @@ This is the file where we define our action's URL matching. The generated file c **Generated routing.yml** -``` brush: +```yaml: ez_systems_cookbook_homepage: path: /hello/{name} defaults: { _controller: EzSystemsCookbookBundle:Default:index } @@ -124,7 +112,7 @@ We can safely remove this default code, and replace it with this: **Edited routing.yml** -``` brush: +```yaml: ezsystems_cookbook_hello: path: /cookbook/hello/{name} defaults: { _controller: EzSystemsCookbookBundle:Default:hello } @@ -138,7 +126,7 @@ This controller was generated by the bundle generator. It contains one method,  **DefaultController::helloAction()** -``` brush: +```javascript: public function helloAction( $name ) { $response = new \Symfony\Component\HttpFoundation\Response; @@ -171,7 +159,6 @@ With both command line scripts and HTTP routes, you have the basics you need to # Browsing, finding, viewing -Created by Dominika Kurek, last modified on Jun 28, 2017 We will start by going through the various ways to find and retrieve content from eZ Platform using the API. While this will be covered in further dedicated documentation, it is necessary to explain a few basic concepts of the Public API. In the following recipes, you will learn about the general principles of the API as they are introduced in individual recipes. @@ -183,7 +170,7 @@ Let's first see the full code. You can see the Command line version at getContainer()->get( 'ezpublish.api.repository' ); $contentService = $repository->getContentService(); $contentTypeService = $repository->getContentTypeService(); @@ -219,7 +206,7 @@ catch( \eZ\Publish\API\Repository\Exceptions\UnauthorizedException $e ) Let's analyze this code block by block. -``` brush: +```php: $repository = $this->getContainer()->get( 'ezpublish.api.repository' ); $contentService = $repository->getContentService(); $contentTypeService = $repository->getContentTypeService(); @@ -228,7 +215,7 @@ $fieldTypeService = $repository->getFieldTypeService(); This is the initialization part. As explained above, everything in the Public API goes through the repository via dedicated services. We get the repository from the service container, using the method `get()` of our container, obtained via `$this->getContainer()`. Using our `$repository` variable, we fetch the two services we will need using `getContentService()` and `getFieldTypeService()`. -``` brush: +```php: try { // iterate over the field definitions of the content type and print out each field's identifier and value @@ -239,7 +226,7 @@ Everything starting from line 5 is about getting our Content and iterating over The first thing we do is use the Content Service to load a Content item using its ID, 66: `$contentService->loadContent ` `( 66 )`. As you can see on the API doc page, this method expects a Content ID, and returns a [Content Value Object](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/Values/Content/Content.html). -``` brush: +```php: foreach( $contentType->fieldDefinitions as $fieldDefinition ) { // ignore ezpage @@ -278,13 +265,13 @@ If you want to take SiteAccess languages into account, you have two options: Otherwise if you want to use an altogether different language, you can specify a language code in the `getField()` call: -``` brush: +```php: $content->getFieldValue( $fieldDefinition->identifier, 'fre-FR' ) ``` **Exceptions handling** -``` brush: +``` php: catch ( \eZ\Publish\API\Repository\Exceptions\NotFoundException $e ) { $output->writeln( "No content with id $contentId found" ); @@ -311,7 +298,7 @@ In this code, we introduce the [LocationService](http://apidoc.ez.no/sami/trunk/ **Loading a Location** -``` brush: +``` php: try { // load the starting location and browse @@ -332,7 +319,7 @@ As for the ContentService, `loadLocation()` returns a Value Object, here a ` **Iterating over a Location's children** -``` brush: +``` php: private function browseLocation( Location $location, OutputInterface $output, $depth = 0 ) { $childLocationList = $this->locationService->loadLocationChildren( $location, $offset = 0, $limit = -1 ); @@ -366,7 +353,7 @@ We introduce here several new services: [`URLAliasService`](http://apidoc.ez.no/ **Services initialization** -``` brush: +``` php: /** @var $repository \eZ\Publish\API\Repository\Repository */ $repository = $this->getContainer()->get( 'ezpublish.api.repository' ); $contentService = $repository->getContentService(); @@ -380,7 +367,7 @@ $userService = $repository->getUserService(); In a command line script, the repository runs as if executed by the anonymous user. In order to identify it as a different user, you need to use the ` UserService ` as follows (in this example `14` is the ID of the administrator user): -``` brush: +``` php: $administratorUser = $userService->loadUser( 14 ); $repository->setCurrentUser( $administratorUser ); ``` @@ -393,7 +380,7 @@ V1.6 Since v1.6.0, as the `setCurrentUser` method is deprecated, you need to use the following code (here for the `admin` user, to be replaced with a different login as needed): -``` brush: +``` php: $permissionResolver = $repository->getPermissionResolver(); $user = $userService->loadUserByLogin('admin'); $permissionResolver->setCurrentUserReference($user); @@ -403,7 +390,7 @@ $permissionResolver->setCurrentUserReference($user); We will now load a `ContentInfo` object using the provided ID and use it to get our Content item's metadata -``` brush: +``` php: $contentInfo = $contentService->loadContentInfo( $contentId ); ``` @@ -411,7 +398,7 @@ $contentInfo = $contentService->loadContentInfo( $contentId ); **Getting Content Locations** -``` brush: +``` php: // show all locations of the content $locations = $locationService->loadLocations( $contentInfo ); $output->writeln( "LOCATIONS" ); @@ -432,7 +419,7 @@ We now want to list relations from and to our Content. Since relations are versi **Browsing a Content's relations** -``` brush: +``` php: // show all relations of the current version $versionInfo = $contentService->loadVersionInfo( $contentInfo ); $relations = $contentService->loadRelations( $versionInfo ); @@ -455,7 +442,7 @@ We can of course get our Content item's metadata by using the Value Object's pro **Primitive object metadata** -``` brush: +``` php: // show meta data $output->writeln( "\nMETADATA" ); $output->writeln( " Name: " . $contentInfo->name ); @@ -471,7 +458,7 @@ $output->writeln( " Always available: " . ( $contentInfo->alwaysAv We can use [`UserService::loadUser()`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/UserService.html#method_loadUser) with Content `ownerId` property of our `ContentInfo` to load the Content's owner as a ` User ` Value Object. -``` brush: +``` php: $owner = $userService->loadUser( $contentInfo->ownerId ); $output->writeln( " Owner: " . $owner->contentInfo->name ); ``` @@ -482,7 +469,7 @@ To get the current version's creator, and not the content's owner, you need to u The Section's ID can be found in the `sectionId` property of the `ContentInfo` object. To get the matching Section Value Object, you need to use the `SectionService::loadSection()` method. -``` brush: +``` php: $section = $sectionService->loadSection( $contentInfo->sectionId ); $output->writeln( " Section: $section->name" ); ``` @@ -491,7 +478,7 @@ $output->writeln( " Section: $section->name" ); To conclude we can also iterate over the Content's version, as ` VersionInfo ` Value Objects. -``` brush: +``` php: $versionInfoArray = $contentService->loadVersions( $contentInfo ); if ( !empty( $versionInfoArray ) ) { @@ -550,7 +537,7 @@ We introduce here a new object: `Query`. It is used to build up a Content query   -``` brush: +```php: $query = new \eZ\Publish\API\Repository\Values\Content\Query(); // Use 'query' over 'filter' for FullText to get hit score (relevancy) with Solr/Elastic $query->query = new Query\Criterion\FullText( $text ); @@ -568,7 +555,7 @@ The full list of criteria can be found on your installation in the following dir The `Query` object is given as an argument to [`SearchService::findContent()`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/SearchService.html#method_findContent). This method returns a `SearchResult` object. This object provides you with various information about the search operation (number of results, time taken, spelling suggestions, or facets, as well as, of course, the results themselves. -``` brush: +``` php: $result = $searchService->findContent( $query ); $output->writeln( 'Found ' . $result->totalCount . ' items' ); foreach ( $result->searchHits as $searchHit ) @@ -601,7 +588,7 @@ Full code As explained in the previous chapter, Criterion objects are grouped together using logical criteria. We will now see how multiple criteria objects can be combined into a fine grained search `Query`. -``` brush: +``` php: use eZ\Publish\API\Repository\Values\Content\Query\Criterion; use eZ\Publish\API\Repository\Values\Content;   @@ -635,7 +622,7 @@ Note that the criterion behaves differently depending on the method you use, bec This example shows the usage of both `$languageFilter` and `Criterion\Visibility`: -``` brush: +``` php: $query = new LocationQuery([ 'filter' => new Criterion\LogicalAnd([ new Criterion\Visibility(Criterion\Visibility::VISIBLE), @@ -657,7 +644,7 @@ A search isn't only meant for searching, it also provides the interface for what Following the examples above we now change it a bit to combine several criteria with both an AND and an OR condition. -``` brush: +``` javascript: use eZ\Publish\API\Repository\Values\Content\Query\Criterion; use eZ\Publish\API\Repository\Values\Content;   @@ -691,7 +678,7 @@ The above example is fine, but it can be optimized a bit by taking advantage of You can also use the [`ContentTypeIdentifier`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/Values/Content/Query/Criterion/ContentTypeIdentifier.html) Criterion: -``` brush: +``` php: use eZ\Publish\API\Repository\Values\Content\Query\Criterion; use eZ\Publish\API\Repository\Values\Content;   @@ -708,7 +695,7 @@ $query->filter = new Criterion\LogicalAnd( $result = $searchService->findContent( $query ); ``` -Tip +**Tip** All filter criteria are capable of doing an "IN" selection, the ParentLocationId above could, for example, have been provided "array( 2, 43 )" to include second level children in both your content tree (2) and your media tree (43). @@ -737,7 +724,7 @@ To be able to take advantage of facets, we can set the `Query->facetBuilders` pr As an example, let's `apply UserFacet ` to be able to group content according to the creator: -``` brush: +``` php: use eZ\Publish\API\Repository\Values\Content\Query\Criterion; use eZ\Publish\API\Repository\Values\Content\Query\FacetBuilder;   @@ -766,7 +753,7 @@ Thanks to the fact that the " searchHits " property of the [`SearchResult`](http   -``` brush: +``` php: use eZ\Publish\API\Repository\Values\Content\Query;   // [...] @@ -782,7 +769,6 @@ $resultCount = $searchService->findContent( $query )->totalCount; # Managing Content -Created by Dominika Kurek, last modified on Jun 06, 2017 In the following recipes, you will see how to create Content, including complex fields like XmlText or Image. @@ -792,7 +778,7 @@ As seen earlier, the Repository executes operations with a user's credentials. I **authentication** -``` brush: +``` php: $user = $userService->loadUserByCredentials( $username, $password ); $repository->setCurrentUser( $user ); ``` @@ -803,7 +789,7 @@ Since v1.6.0, as the `setCurrentUser` method is deprecated, you need to use the **authentication** -``` brush: +``` php: $permissionResolver = $repository->getPermissionResolver(); $user = $userService->loadUserByCredentials( $username, $password ); $permissionResolver->setCurrentUserReference($user); @@ -817,7 +803,7 @@ Full code We will now see how to create Content using the Public API. This example will work with the default Folder (ID 1) Content Type from eZ Platform. -``` brush: +``` php: /** @var $repository \eZ\Publish\API\Repository\Repository */ $repository = $this->getContainer()->get( 'ezpublish.api.repository' ); $contentService = $repository->getContentService(); @@ -831,7 +817,7 @@ We first need the required services. In this case: `ContentService`, `LocationSe As explained in [eZ Platform Public PHP API](eZ-Platform-Public-PHP-API_31429583.html), Value Objects are read only. Dedicated objects are provided for Update and Create operations: structs, like `ContentCreateStruct` or `UpdateCreateStruct`. In this case, we need to use a `ContentCreateStruct`.  -``` brush: +``` php: $contentType = $contentTypeService->loadContentTypeByIdentifier( 'article' ); $contentCreateStruct = $contentService->newContentCreateStruct( $contentType, 'eng-GB' ); ``` @@ -840,7 +826,7 @@ We first need to get the [`ContentType`](http://apidoc.ez.no/sami/trunk/NS/html/ ### Setting the fields values -``` brush: +``` php: $contentCreateStruct->setField( 'title', 'My title' ); $contentCreateStruct->setField( 'intro', $intro ); $contentCreateStruct->setField( 'body', $body ); @@ -856,7 +842,7 @@ In any case, whatever the Field Type is, a Value of this type can be provided. F In order to set a Location for our object, we must instantiate a [`LocationCreateStruct`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/Values/Content/LocationCreateStruct.html). This is done with `LocationService::newLocationCreateStruct()`, with the new Location's parent ID as an argument. -``` brush: +``` php: $locationCreateStruct = $locationService->newLocationCreateStruct( 2 ); ``` @@ -864,7 +850,7 @@ $locationCreateStruct = $locationService->newLocationCreateStruct( 2 ); To actually create our Content in the Repository, we need to use `ContentService::createContent()`. This method expects a `ContentCreateStruct`, as well as a `LocationCreateStruct`. We have created both in the previous steps. -``` brush: +``` php: $draft = $contentService->createContent( $contentCreateStruct, array( $locationCreateStruct ) ); $content = $contentService->publishVersion( $draft->versionInfo ); ``` @@ -881,14 +867,14 @@ Full code We will now see how the previously created Content can be updated. To do so, we will create a new draft for our Content, update it using a [`ContentUpdateStruct`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/Values/Content/ContentUpdateStruct.html), and publish the updated Version. -``` brush: +``` php: $contentInfo = $contentService->loadContentInfo( $contentId ); $contentDraft = $contentService->createContentDraft( $contentInfo ); ``` To create our draft, we need to load the Content item's ContentInfo using `ContentService::loadContentInfo()`. We can then use `ContentService::createContentDraft()` to add a new Draft to our Content. -``` brush: +``` php: // instantiate a content update struct and set the new fields $contentUpdateStruct = $contentService->newContentUpdateStruct(); $contentUpdateStruct->initialLanguageCode = 'eng-GB'; // set language for new version @@ -898,7 +884,7 @@ $contentUpdateStruct->setField( 'body', $newBody ); To set the new values for this version, we request a `ContentUpdateStruct` from the `ContentService` using the `newContentUpdateStruct()` method. Updating the values hasn't changed: we use the `setField()` method. -``` brush: +``` php: $contentDraft = $contentService->updateContent( $contentDraft->versionInfo, $contentUpdateStruct ); $content = $contentService->publishVersion( $contentDraft->versionInfo ); ``` @@ -911,7 +897,7 @@ In the two previous examples, you have seen that we set the ContentUpdateStruct' **translating** -``` brush: +``` php: $contentUpdateStruct->initialLanguageCode = 'ger-DE'; $contentUpdateStruct->setField( 'title', $newtitle ); $contentUpdateStruct->setField( 'body', $newbody ); @@ -921,7 +907,7 @@ It is possible to create or update content in multiple languages at once. There **update multiple languages** -``` brush: +``` php: // set one language for new version $contentUpdateStruct->initialLanguageCode = 'fre-FR'; @@ -944,7 +930,7 @@ As explained above, the `setField()` method can accept various values: an instan We assume that we use the default image class. Creating our Content, using the Content Type and a ContentCreateStruct, has been covered above, and can be found in the full code. Let's focus on how the image is provided. -``` brush: +``` php: $file = '/path/to/image.png'; $value = new \eZ\Publish\Core\FieldType\Image\Value( @@ -962,13 +948,13 @@ This time, we create our image by directly providing an [`Image\Value`](http://a Images also implement a static [`fromString()`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/Core/FieldType/Image/Value.html#method_fromString) method that will, given a path to an image, return an `Image\Value` object. -``` brush: +``` php: $value = \eZ\Publish\Core\FieldType\Image\Value::fromString( '/path/to/image.png' ); ``` But as said before, whatever you provide `setField()` with is sent to the `acceptValue()` method. This method really is the entry point to the input formats a Field Type accepts. In this case, you could have provided setField with either a hash, similar to the one we provided the Image\\Value constructor with, or the path to your image, as a string. -``` brush: +``` php: $contentCreateStruct->setField( 'image', '/path/to/image.png' );   // or @@ -991,7 +977,7 @@ Another very commonly used Field Type is the rich text one, `XmlText`. **working with xml text** -``` brush: +``` php: $xmlText = <<< EOX
@@ -1012,14 +998,14 @@ Using a custom format as input More input formats will be added later. The API for that is actually already available: you simply need to implement the [`XmlText\Input`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/Core/FieldType/XmlText/Input.html) interface. It contains one method, [`getInternalRepresentation()`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/Core/FieldType/XmlText/Input.html#method_getInternalRepresentation), that must return an internal XML string. Create your own bundle, add your implementation to it, and use it in your code! -``` brush: +``` php: $input = new \My\XmlText\CustomInput( 'My custom format string' ); $contentCreateStruct->setField( 'body', $input ); ``` ## Deleting Content -``` brush: +``` php: $contentService->deleteContent( $contentInfo ); ``` @@ -1030,7 +1016,6 @@ Use with caution! # Working with Locations -Created by Dominika Kurek, last modified on Apr 22, 2016 ## Adding a new Location to a Content item @@ -1040,7 +1025,7 @@ Full code We have seen earlier how you can create a Location for a newly created `Content`. It is of course also possible to add a new [`Location`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/Values/Content/Location.html) to an existing `Content`. -``` brush: +``` php: try { $locationCreateStruct = $locationService->newLocationCreateStruct( $parentLocationId ); @@ -1062,7 +1047,7 @@ catch ( \eZ\Publish\API\Repository\Exceptions\UnauthorizedException $e ) This is the required code. As you can see, both the ContentService and the LocationService are involved. Errors are handled the usual way, by intercepting the Exceptions the used methods may throw. -``` brush: +``` php: $locationCreateStruct = $locationService->newLocationCreateStruct( $parentLocationId ); ``` @@ -1070,13 +1055,13 @@ Like we do when creating a new Content item, we need to get a new `LocationCreat In this example, we use the default values for the various `LocationCreateStruct` properties. We could of course have set custom values, like setting the Location as hidden ($location->hidden = true), or changed the remoteId (`$location->remoteId = $myRemoteId`). -``` brush: +``` php: $contentInfo = $contentService->loadContentInfo( $contentId ); ``` To add a Location to a Content item, we need to specify the Content, using a [`ContentInfo`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/Values/Content/ContentInfo.html) object. We load one using `ContentService::loadContentInfo()`, using the Content ID as the argument. -``` brush: +``` php: $newLocation = $locationService->createLocation( $contentInfo, $locationCreateStruct ); ``` @@ -1090,7 +1075,7 @@ Full code We mentioned earlier that a Location's visibility could be set while creating the Location, using the hidden property of the LocationCreateStruct. Changing a Location's visibility may have a large impact in the Repository: doing so will affect the Location's subtree visibility. For this reason, a `LocationUpdateStruct` doesn't let you toggle this property. You need to use the `LocationService` to do so. -``` brush: +``` php: $hiddenLocation = $locationService->hideLocation( $location ); $unhiddenLocation = $locationService->unhideLocation( $hiddenLocation ); ``` @@ -1103,13 +1088,13 @@ The explanation above is valid for most Repository objects. Modification of prop Deleting Locations can be done in two ways: delete, or trash.  -``` brush: +``` php: $locationService->deleteLocation( $locationInfo ); ``` [`LocationService::deleteLocation()`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/LocationService.html#method_deleteLocation) will permanently delete the Location, as well as all its descendants. Content that has only one Location will be permanently deleted as well. Those with more than one won't be, as they are still referenced by at least one Location. -``` brush: +``` php: $trashService->trash( $locationInfo ); ``` @@ -1121,7 +1106,7 @@ The `TrashService` can be used to list, restore and delete Locations that were p This is done using the `ContentService`, by updating the `ContentInfo` with a `ContentUpdateStruct` that sets the new main location: -``` brush: +``` php: $repository = $this->getContainer()->get( 'ezpublish.api.repository' ); $contentService = $repository->getContentService(); $contentInfo = $contentService->loadContentInfo( $contentId ); @@ -1137,7 +1122,6 @@ Credits to [Gareth Arnott](https://doc.ez.no/display/~arnottg) for the snippet. # Other recipes -Created by Dominika Kurek, last modified on Apr 22, 2016 ## Assigning Section to content @@ -1149,7 +1133,7 @@ The Section that a Content item belongs to can be set during creation, using the **assign section to content** -``` brush: +``` php: $contentInfo = $contentService->loadContentInfo( $contentId ); $section = $sectionService->loadSection( $sectionId ); $sectionService->assignSection( $contentInfo, $section ); @@ -1159,7 +1143,7 @@ This operation involves the `SectionService`, as well as the `ContentService`. **assign section to content** -``` brush: +``` php: $contentInfo = $contentService->loadContentInfo( $contentId ); ``` @@ -1167,7 +1151,7 @@ We use `ContentService::loadContentInfo()` to get the Content we want to update **assign section to content** -``` brush: +``` php: $section = $sectionService->loadSection( $sectionId ); ``` @@ -1175,7 +1159,7 @@ $section = $sectionService->loadSection( $sectionId ); **assign section to content** -``` brush: +``` php: $sectionService->assignSection( $contentInfo, $section ); ``` @@ -1193,7 +1177,7 @@ Creating a `ContentType` is actually almost more complex than creating Content. Let's split the code in three major parts. -``` brush: +``` php: try { $contentTypeGroup = $contentTypeService->loadContentTypeGroupByIdentifier( 'content' ); @@ -1227,7 +1211,7 @@ Using the create struct's properties, we can set the Type's properties: The next big part is to add FieldDefinition objects to our Content Type. -``` brush: +```php: // add a TextLine Field with identifier 'title' $titleFieldCreateStruct = $contentTypeService->newFieldDefinitionCreateStruct( 'title', 'ezstring' ); $titleFieldCreateStruct->names = array( 'eng-GB' => 'Title' ); @@ -1263,7 +1247,7 @@ Each field's properties are set using the create struct's properties: Once the properties for each create struct are set, the field is added to the Content Type create struct using [`ContentTypeCreateStruct::addFieldDefinition()`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/Values/ContentType/ContentTypeCreateStruct.html#method_addFieldDefinition). -``` brush: +``` php: try { $contentTypeDraft = $contentTypeService->createContentType( $contentTypeCreateStruct, array( $contentTypeGroup ) ); diff --git a/docs/api/rest_api_guide.md b/docs/api/rest_api_guide.md index a1885e911b..5768c0cd5d 100644 --- a/docs/api/rest_api_guide.md +++ b/docs/api/rest_api_guide.md @@ -1,10 +1,8 @@ -1. [Developer](index.html) -2. [Documentation](Documentation_31429504.html) -3. [API](API_31429524.html) + # REST API Guide -Created by Dominika Kurek, last modified by David Christian Liedle on Jul 11, 2016 + The REST API v2 introduced in eZ Platform allows you to interact with an eZ Platform installation using the HTTP protocol, following a [REST](http://en.wikipedia.org/wiki/Representational_state_transfer) interaction model. @@ -52,28 +50,12 @@ Other headers will be used in HTTP requests for specifying the siteaccess to int Responses returned by the API will also use custom headers to indicate information about the executed operation. -  - -#### In this topic: - -- [Accessing the REST API](#RESTAPIGuide-AccessingtheRESTAPI) -- [Basics](#RESTAPIGuide-Basics) - - [Resources](#RESTAPIGuide-Resources) - - [HTTP verbs](#RESTAPIGuide-HTTPverbs) - - [Media type headers](#RESTAPIGuide-Mediatypeheaders) - - [Other headers](#RESTAPIGuide-Otherheaders) - -#### Related topics: - -- [REST API reference](REST-API-reference_31430594.html) -- [Getting started with the REST API](Getting-started-with-the-REST-API_31430289.html) # Getting started with the REST API -Created by Dominika Kurek, last modified on Apr 22, 2016 ## Installation @@ -91,7 +73,7 @@ To enable basic auth based authentication, you need to edit `app/config/security **security.yml** -``` brush: +```yaml: security: # ... firewalls: @@ -114,7 +96,7 @@ One of the main reasons for this API is to help implement JavaScript / AJAX inte **REST API with JavaScript** -``` brush: +```javascript: 

 
 
 
 ```
 
-### With Bower
+## With Bower
 
 Alternatively, the JavaScript REST Client can be installed directly in any project with [Bower](http://bower.io/):
 
 **Installing with bower**
 
-``` php:
+``` php
 $ bower install --save ezsystems/ez-js-rest-client
 ```
 
@@ -58,22 +58,22 @@ In essence, the operations available through those services are asynchronous, so
 1.  `error`: depending on the success of the operation, this parameter is either `false` or a [`CAPIError`](http://ezsystems.github.io/javascript-rest-client/classes/CAPIError.html) instance representing the error
 2.  `response`: it's always of a [`Response`](http://ezsystems.github.io/javascript-rest-client/classes/Response.html) instance allowing you to retrieve any information from the REST API response
 
-### Instantiation and authentication
+## Instantiation and authentication
 
 [The `eZ.CAPI` constructor function](http://ezsystems.github.io/javascript-rest-client/classes/CAPI.html) expects two parameters:
 
 1.  the API end point URI
-2.  an authentication agent instance to configure the client for [the authentication mechanism configuration in eZ Platform](REST-API-Authentication_31430293.html).
+2.  an authentication agent instance to configure the client for [the authentication mechanism configuration in eZ Platform](../general_rest_usage.md#REST-API-Authentication).
 
 The JavaScript REST Client comes with two authentication agents for the Session and Basic Auth authentication mechanism.
 
-#### Session auth
+## Session auth
 
 The Session Auth Agent expects an object describing the existing Session or containing the credentials for the user to create the corresponding session. So if the user is not yet authenticated, the client can be instantiated with:
 
 **Session Authentication (new session)**
 
-``` php:
+``` php
 var capi,
     credentials = {
         login: 'admin',
@@ -99,7 +99,7 @@ If the user already has a session, the agent expects an object describing the se
 
 **Session Authentication (existing session)**
 
-``` :
+```
 var capi,
     sessionInfo = {
         name: 'eZSESSID', // name of the session, might also be something like eZSESSID98defd6ee70dfb1dea416cecdf391f58
@@ -121,13 +121,13 @@ capi.isLoggedIn(function (error, response) {
 });
 ```
 
-#### Basic auth
+## Basic auth
 
 When configured in the Basic Authentication, the basic auth agent just expects the user's credentials:
 
 **Basic Authentication**
 
-``` php:
+``` php
 var capi,
     credentials = {
         login: 'admin',
@@ -147,13 +147,13 @@ capi.logIn(function (error, response) {
 });
 ```
 
-### Loading a ContentInfo or a Content
+## Loading a ContentInfo or a Content
 
 To load a ContentInfo, you need [the Content Service](http://ezsystems.github.io/javascript-rest-client/classes/ContentService.html), it is returned by the `getContentService` method on the client instance:
 
 **Loading a ContentInfo**
 
-``` php:
+``` php
 var capi, contentService,
     contentRestId = '/api/ezp/v2/content/objects/1',
     credentials = {
@@ -178,13 +178,13 @@ contentService.loadContentInfo(contentRestId, function (error, response) {
 
 If you run this example, you should see in the browser network panel a GET HTTP request to  with the necessary headers to get a JSON representation of the ContentInfo. If you want to load the Content instead, you can use [the `loadContent` method](http://ezsystems.github.io/javascript-rest-client/classes/ContentService.html#method_loadContent).
 
-### Moving a Location
+## Moving a Location
 
 To move a Location, [the Content Service](http://ezsystems.github.io/javascript-rest-client/classes/ContentService.html) is also needed, this operation will generate a MOVE HTTP request. If configured for the session authentication mechanism, the client will automatically add the CSRF Token.
 
 **Moving a Location**
 
-``` php:
+``` php
 var capi, contentService,
     locationRestId = '/api/ezp/v2/content/locations/1/43/53', // Media/Multimedia in a default install
     newParentLocationRestId = '/api/ezp/v2/content/locations/1/43/52', // Media/Files in a default install
@@ -207,13 +207,13 @@ contentService.moveSubtree(locationRestId, newParentLocationRestId, function (er
 })
 ```
 
-### Searching for Content or Location
+## Searching for Content or Location
 
-Searching for Content or Location can be done with [REST views](https://github.com/ezsystems/ezpublish-kernel/blob/master/doc/specifications/rest/REST-API-V2.rst#views). REST views can be configured with the [search engine criteria](Search_31429673.html#Search-SearchCriteriaReference) to match some Content items or Locations:
+Searching for Content or Location can be done with [REST views](https://github.com/ezsystems/ezpublish-kernel/blob/master/doc/specifications/rest/REST-API-V2.rst#views). REST views can be configured with the [search engine criteria](../guide/search_criteria_reference.md) to match some Content items or Locations:
 
 **REST views**
 
-``` php:
+``` php
 var capi, contentService, query,
     credentials = {
         login: 'admin',
diff --git a/docs/api/public_php_api.md b/docs/api/public_php_api.md
index a1e9c3dcb1..178aec2c33 100644
--- a/docs/api/public_php_api.md
+++ b/docs/api/public_php_api.md
@@ -13,7 +13,7 @@ It will allow you to create, retrieve, update and delete all the eZ Platform obj
 
 **Obtaining the eZ Platform Repository via the service container**
 
-``` php:
+``` php
 /** @var $repository \eZ\Publish\API\Repository\Repository
 $repository = $container->get( 'ezpublish.api.repository' );
 ```
@@ -102,7 +102,7 @@ This is the file where we define our action's URL matching. The generated file c
 
 **Generated routing.yml**
 
-```yaml:
+``` yaml
 ez_systems_cookbook_homepage:
     path:     /hello/{name}
     defaults: { _controller: EzSystemsCookbookBundle:Default:index }
@@ -112,7 +112,7 @@ We can safely remove this default code, and replace it with this:
 
 **Edited routing.yml**
 
-```yaml:
+``` yaml
 ezsystems_cookbook_hello:
     path:     /cookbook/hello/{name}
     defaults: { _controller: EzSystemsCookbookBundle:Default:hello }
@@ -126,7 +126,7 @@ This controller was generated by the bundle generator. It contains one method, 
 
 **DefaultController::helloAction()**
 
-```javascript:
+``` javascript
 public function helloAction( $name )
 {
     $response = new \Symfony\Component\HttpFoundation\Response;
@@ -170,7 +170,7 @@ Let's first see the full code. You can see the Command line version at getContainer()->get( 'ezpublish.api.repository' );
 $contentService = $repository->getContentService();
 $contentTypeService = $repository->getContentTypeService();
@@ -206,7 +206,7 @@ catch( \eZ\Publish\API\Repository\Exceptions\UnauthorizedException $e )
 
 Let's analyze this code block by block.
 
-```php:
+``` php
 $repository = $this->getContainer()->get( 'ezpublish.api.repository' );
 $contentService = $repository->getContentService();
 $contentTypeService = $repository->getContentTypeService();
@@ -215,7 +215,7 @@ $fieldTypeService = $repository->getFieldTypeService();
 
 This is the initialization part. As explained above, everything in the Public API goes through the repository via dedicated services. We get the repository from the service container, using the method `get()` of our container, obtained via `$this->getContainer()`. Using our `$repository` variable, we fetch the two services we will need using `getContentService()` and `getFieldTypeService()`.
 
-```php:
+``` php
 try
 {
     // iterate over the field definitions of the content type and print out each field's identifier and value
@@ -226,7 +226,7 @@ Everything starting from line 5 is about getting our Content and iterating over
 
 The first thing we do is use the Content Service to load a Content item using its ID, 66: `$contentService->loadContent   ` `( 66 )`. As you can see on the API doc page, this method expects a Content ID, and returns a [Content Value Object](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/Values/Content/Content.html).
 
-```php:
+``` php
 foreach( $contentType->fieldDefinitions as $fieldDefinition )
 {
     // ignore ezpage
@@ -265,13 +265,13 @@ If you want to take SiteAccess languages into account, you have two options:
 
 Otherwise if you want to use an altogether different language, you can specify a language code in the `getField()` call:
 
-```php:
+``` php
 $content->getFieldValue( $fieldDefinition->identifier, 'fre-FR' )
 ```
 
 **Exceptions handling**
 
-``` php:
+``` php
 catch ( \eZ\Publish\API\Repository\Exceptions\NotFoundException $e )
 {
     $output->writeln( "No content with id $contentId found" );
@@ -298,7 +298,7 @@ In this code, we introduce the [LocationService](http://apidoc.ez.no/sami/trunk/
 
 **Loading a Location**
 
-``` php:
+``` php
 try
 {
     // load the starting location and browse
@@ -319,7 +319,7 @@ As for the ContentService, `loadLocation()` returns a Value Object, here a `
 
 **Iterating over a Location's children**
 
-``` php:
+``` php
 private function browseLocation( Location $location, OutputInterface $output, $depth = 0 )
 {
     $childLocationList = $this->locationService->loadLocationChildren( $location, $offset = 0, $limit = -1 );
@@ -353,7 +353,7 @@ We introduce here several new services: [`URLAliasService`](http://apidoc.ez.no/
 
 **Services initialization**
 
-``` php:
+``` php
 /** @var $repository \eZ\Publish\API\Repository\Repository */
 $repository = $this->getContainer()->get( 'ezpublish.api.repository' );
 $contentService = $repository->getContentService();
@@ -367,7 +367,7 @@ $userService = $repository->getUserService();
 
 In a command line script, the repository runs as if executed by the anonymous user. In order to identify it as a different user, you need to use the `         UserService       ` as follows (in this example `14` is the ID of the administrator user):
 
-``` php:
+``` php
 $administratorUser = $userService->loadUser( 14 );
 $repository->setCurrentUser( $administratorUser );
 ```
@@ -380,7 +380,7 @@ V1.6
 
 Since v1.6.0, as the `setCurrentUser` method is deprecated, you need to use the following code (here for the `admin` user, to be replaced with a different login as needed):
 
-``` php:
+``` php
 $permissionResolver = $repository->getPermissionResolver();
 $user = $userService->loadUserByLogin('admin');
 $permissionResolver->setCurrentUserReference($user);
@@ -390,7 +390,7 @@ $permissionResolver->setCurrentUserReference($user);
 
 We will now load a `ContentInfo` object using the provided ID and use it to get our Content item's metadata
 
-``` php:
+``` php
 $contentInfo = $contentService->loadContentInfo( $contentId );
 ```
 
@@ -398,7 +398,7 @@ $contentInfo = $contentService->loadContentInfo( $contentId );
 
 **Getting Content Locations**
 
-``` php:
+``` php
 // show all locations of the content
 $locations = $locationService->loadLocations( $contentInfo );
 $output->writeln( "LOCATIONS" );
@@ -419,7 +419,7 @@ We now want to list relations from and to our Content. Since relations are versi
 
 **Browsing a Content's relations**
 
-``` php:
+``` php
 // show all relations of the current version
 $versionInfo = $contentService->loadVersionInfo( $contentInfo );
 $relations = $contentService->loadRelations( $versionInfo );
@@ -442,7 +442,7 @@ We can of course get our Content item's metadata by using the Value Object's pro
 
 **Primitive object metadata**
 
-``` php:
+``` php
 // show meta data
 $output->writeln( "\nMETADATA" );
 $output->writeln( "  Name: " . $contentInfo->name );
@@ -458,7 +458,7 @@ $output->writeln( "  Always available: " . ( $contentInfo->alwaysAv
 
 We can use [`UserService::loadUser()`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/UserService.html#method_loadUser) with Content `ownerId` property of our `ContentInfo` to load the Content's owner as a `     User   ` Value Object.
 
-``` php:
+``` php
 $owner = $userService->loadUser( $contentInfo->ownerId );
 $output->writeln( "  Owner: " . $owner->contentInfo->name );
 ```
@@ -469,7 +469,7 @@ To get the current version's creator, and not the content's owner, you need to u
 
 The Section's ID can be found in the `sectionId` property of the `ContentInfo` object. To get the matching Section Value Object, you need to use the `SectionService::loadSection()` method.
 
-``` php:
+``` php
 $section = $sectionService->loadSection( $contentInfo->sectionId );
 $output->writeln( "  Section: $section->name" );
 ```
@@ -478,7 +478,7 @@ $output->writeln( "  Section: $section->name" );
 
 To conclude we can also iterate over the Content's version, as `     VersionInfo   ` Value Objects.
 
-``` php:
+``` php
 $versionInfoArray = $contentService->loadVersions( $contentInfo );
 if ( !empty( $versionInfoArray ) )
 {
@@ -537,7 +537,7 @@ We introduce here a new object: `Query`. It is used to build up a Content query
 
  
 
-```php:
+```php
 $query = new \eZ\Publish\API\Repository\Values\Content\Query();
 // Use 'query' over 'filter' for FullText to get hit score (relevancy) with Solr/Elastic
 $query->query = new Query\Criterion\FullText( $text );
@@ -555,7 +555,7 @@ The full list of criteria can be found on your installation in the following dir
 
 The `Query` object is given as an argument to [`SearchService::findContent()`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/SearchService.html#method_findContent). This method returns a `SearchResult` object. This object provides you with various information about the search operation (number of results, time taken, spelling suggestions, or facets, as well as, of course, the results themselves.
 
-``` php:
+``` php
 $result = $searchService->findContent( $query );
 $output->writeln( 'Found ' . $result->totalCount . ' items' );
 foreach ( $result->searchHits as $searchHit )
@@ -588,7 +588,7 @@ Full code
 
 As explained in the previous chapter, Criterion objects are grouped together using logical criteria. We will now see how multiple criteria objects can be combined into a fine grained search `Query`.
 
-``` php:
+``` php
 use eZ\Publish\API\Repository\Values\Content\Query\Criterion;
 use eZ\Publish\API\Repository\Values\Content;
  
@@ -622,7 +622,7 @@ Note that the criterion behaves differently depending on the method you use, bec
 
 This example shows the usage of both `$languageFilter` and `Criterion\Visibility`:
 
-``` php:
+``` php
 $query = new LocationQuery([
     'filter' => new Criterion\LogicalAnd([
     new Criterion\Visibility(Criterion\Visibility::VISIBLE),
@@ -644,7 +644,7 @@ A search isn't only meant for searching, it also provides the interface for what
 
 Following the examples above we now change it a bit to combine several criteria with both an AND and an OR condition.
 
-``` javascript:
+``` javascript
 use eZ\Publish\API\Repository\Values\Content\Query\Criterion;
 use eZ\Publish\API\Repository\Values\Content;
  
@@ -678,7 +678,7 @@ The above example is fine, but it can be optimized a bit by taking advantage of
 
 You can also use the [`ContentTypeIdentifier`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/Values/Content/Query/Criterion/ContentTypeIdentifier.html) Criterion:
 
-``` php:
+``` php
 use eZ\Publish\API\Repository\Values\Content\Query\Criterion;
 use eZ\Publish\API\Repository\Values\Content;
  
@@ -724,7 +724,7 @@ To be able to take advantage of facets, we can set the `Query->facetBuilders` pr
 
 As an example, let's `apply UserFacet         ` to be able to group content according to the creator:
 
-``` php:
+``` php
 use eZ\Publish\API\Repository\Values\Content\Query\Criterion;
 use eZ\Publish\API\Repository\Values\Content\Query\FacetBuilder;
  
@@ -753,7 +753,7 @@ Thanks to the fact that the " searchHits " property of the [`SearchResult`](http
 
  
 
-``` php:
+``` php
 use eZ\Publish\API\Repository\Values\Content\Query;
  
 // [...]
@@ -778,7 +778,7 @@ As seen earlier, the Repository executes operations with a user's credentials. I
 
 **authentication**
 
-``` php:
+``` php
 $user = $userService->loadUserByCredentials( $username, $password );
 $repository->setCurrentUser( $user );
 ```
@@ -789,7 +789,7 @@ Since v1.6.0, as the `setCurrentUser` method is deprecated, you need to use the
 
 **authentication**
 
-``` php:
+``` php
 $permissionResolver = $repository->getPermissionResolver();
 $user = $userService->loadUserByCredentials( $username, $password );
 $permissionResolver->setCurrentUserReference($user);
@@ -803,7 +803,7 @@ Full code
 
 We will now see how to create Content using the Public API. This example will work with the default Folder (ID 1) Content Type from eZ Platform.
 
-``` php:
+``` php
 /** @var $repository \eZ\Publish\API\Repository\Repository */
 $repository = $this->getContainer()->get( 'ezpublish.api.repository' );
 $contentService = $repository->getContentService();
@@ -817,7 +817,7 @@ We first need the required services. In this case: `ContentService`, `LocationSe
 
 As explained in [eZ Platform Public PHP API](eZ-Platform-Public-PHP-API_31429583.html), Value Objects are read only. Dedicated objects are provided for Update and Create operations: structs, like `ContentCreateStruct` or `UpdateCreateStruct`. In this case, we need to use a `ContentCreateStruct`. 
 
-``` php:
+``` php
 $contentType = $contentTypeService->loadContentTypeByIdentifier( 'article' );
 $contentCreateStruct = $contentService->newContentCreateStruct( $contentType, 'eng-GB' );
 ```
@@ -826,7 +826,7 @@ We first need to get the [`ContentType`](http://apidoc.ez.no/sami/trunk/NS/html/
 
 ### Setting the fields values
 
-``` php:
+``` php
 $contentCreateStruct->setField( 'title', 'My title' );
 $contentCreateStruct->setField( 'intro', $intro );
 $contentCreateStruct->setField( 'body', $body );
@@ -838,19 +838,19 @@ The `         ContentCreateStruct::setField()       ` method can take several ty
 
 In any case, whatever the Field Type is, a Value of this type can be provided. For instance, a TextLine\\Value can be provided for a TextLine\\Type. Depending on the Field Type implementation itself, more specifically on the `fromHash()` method every Field Type implements, various arrays can be accepted, as well as primitive types, depending on the Type.
 
-### Setting the Location
+## Setting the Location
 
 In order to set a Location for our object, we must instantiate a [`LocationCreateStruct`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/Values/Content/LocationCreateStruct.html). This is done with `LocationService::newLocationCreateStruct()`, with the new Location's parent ID as an argument.
 
-``` php:
+``` php
 $locationCreateStruct = $locationService->newLocationCreateStruct( 2 );
 ```
 
-### Creating and publishing
+## Creating and publishing
 
 To actually create our Content in the Repository, we need to use `ContentService::createContent()`. This method expects a `ContentCreateStruct`, as well as a `LocationCreateStruct`. We have created both in the previous steps.
 
-``` php:
+``` php
 $draft = $contentService->createContent( $contentCreateStruct, array( $locationCreateStruct ) );
 $content = $contentService->publishVersion( $draft->versionInfo );
 ```
@@ -867,14 +867,14 @@ Full code
 
 We will now see how the previously created Content can be updated. To do so, we will create a new draft for our Content, update it using a [`ContentUpdateStruct`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/Values/Content/ContentUpdateStruct.html), and publish the updated Version.
 
-``` php:
+``` php
 $contentInfo = $contentService->loadContentInfo( $contentId );
 $contentDraft = $contentService->createContentDraft( $contentInfo );
 ```
 
 To create our draft, we need to load the Content item's ContentInfo using `ContentService::loadContentInfo()`. We can then use `ContentService::createContentDraft()` to add a new Draft to our Content.
 
-``` php:
+``` php
 // instantiate a content update struct and set the new fields
 $contentUpdateStruct = $contentService->newContentUpdateStruct();
 $contentUpdateStruct->initialLanguageCode = 'eng-GB'; // set language for new version
@@ -884,7 +884,7 @@ $contentUpdateStruct->setField( 'body', $newBody );
 
 To set the new values for this version, we request a `ContentUpdateStruct` from the `ContentService` using the `newContentUpdateStruct()` method. Updating the values hasn't changed: we use the `setField()` method.
 
-``` php:
+``` php
 $contentDraft = $contentService->updateContent( $contentDraft->versionInfo, $contentUpdateStruct );
 $content = $contentService->publishVersion( $contentDraft->versionInfo );
 ```
@@ -897,7 +897,7 @@ In the two previous examples, you have seen that we set the ContentUpdateStruct'
 
 **translating**
 
-``` php:
+``` php
 $contentUpdateStruct->initialLanguageCode = 'ger-DE';
 $contentUpdateStruct->setField( 'title', $newtitle );
 $contentUpdateStruct->setField( 'body', $newbody );
@@ -907,7 +907,7 @@ It is possible to create or update content in multiple languages at once. There
 
 **update multiple languages**
 
-``` php:
+``` php
 // set one language for new version
 $contentUpdateStruct->initialLanguageCode = 'fre-FR';
 
@@ -930,7 +930,7 @@ As explained above, the `setField()` method can accept various values: an instan
 
 We assume that we use the default image class. Creating our Content, using the Content Type and a ContentCreateStruct, has been covered above, and can be found in the full code. Let's focus on how the image is provided.
 
-``` php:
+``` php
 $file = '/path/to/image.png';
 
 $value = new \eZ\Publish\Core\FieldType\Image\Value(
@@ -948,13 +948,13 @@ This time, we create our image by directly providing an [`Image\Value`](http://a
 
 Images also implement a static [`fromString()`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/Core/FieldType/Image/Value.html#method_fromString) method that will, given a path to an image, return an `Image\Value` object.
 
-``` php:
+``` php
 $value = \eZ\Publish\Core\FieldType\Image\Value::fromString( '/path/to/image.png' );
 ```
 
 But as said before, whatever you provide `setField()` with is sent to the `acceptValue()` method. This method really is the entry point to the input formats a Field Type accepts. In this case, you could have provided setField with either a hash, similar to the one we provided the Image\\Value constructor with, or the path to your image, as a string.
 
-``` php:
+``` php
 $contentCreateStruct->setField( 'image', '/path/to/image.png' );
  
 // or
@@ -977,7 +977,7 @@ Another very commonly used Field Type is the rich text one, `XmlText`.
 
 **working with xml text**
 
-``` php:
+``` php
 $xmlText = <<< EOX
 
 

@@ -998,14 +998,14 @@ Using a custom format as input
 
 More input formats will be added later. The API for that is actually already available: you simply need to implement the [`XmlText\Input`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/Core/FieldType/XmlText/Input.html) interface. It contains one method, [`getInternalRepresentation()`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/Core/FieldType/XmlText/Input.html#method_getInternalRepresentation), that must return an internal XML string. Create your own bundle, add your implementation to it, and use it in your code!
 
-``` php:
+``` php
 $input = new \My\XmlText\CustomInput( 'My custom format string' );
 $contentCreateStruct->setField( 'body', $input );
 ```
 
 ## Deleting Content
 
-``` php:
+``` php
 $contentService->deleteContent( $contentInfo );
 ```
 
@@ -1025,7 +1025,7 @@ Full code
 
 We have seen earlier how you can create a Location for a newly created `Content`. It is of course also possible to add a new [`Location`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/Values/Content/Location.html) to an existing `Content`.
 
-``` php:
+``` php
 try
 {
     $locationCreateStruct = $locationService->newLocationCreateStruct( $parentLocationId );
@@ -1047,7 +1047,7 @@ catch ( \eZ\Publish\API\Repository\Exceptions\UnauthorizedException $e )
 
 This is the required code. As you can see, both the ContentService and the LocationService are involved. Errors are handled the usual way, by intercepting the Exceptions the used methods may throw.
 
-``` php:
+``` php
 $locationCreateStruct = $locationService->newLocationCreateStruct( $parentLocationId );
 ```
 
@@ -1055,13 +1055,13 @@ Like we do when creating a new Content item, we need to get a new `LocationCreat
 
 In this example, we use the default values for the various `LocationCreateStruct` properties. We could of course have set custom values, like setting the Location as hidden ($location->hidden = true), or changed the remoteId (`$location->remoteId = $myRemoteId`).
 
-``` php:
+``` php
 $contentInfo = $contentService->loadContentInfo( $contentId );
 ```
 
 To add a Location to a Content item, we need to specify the Content, using a [`ContentInfo`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/Values/Content/ContentInfo.html) object. We load one using `ContentService::loadContentInfo()`, using the Content ID as the argument.
 
-``` php:
+``` php
 $newLocation = $locationService->createLocation( $contentInfo, $locationCreateStruct );
 ```
 
@@ -1075,7 +1075,7 @@ Full code
 
 We mentioned earlier that a Location's visibility could be set while creating the Location, using the hidden property of the LocationCreateStruct. Changing a Location's visibility may have a large impact in the Repository: doing so will affect the Location's subtree visibility. For this reason, a `LocationUpdateStruct` doesn't let you toggle this property. You need to use the `LocationService` to do so.
 
-``` php:
+``` php
 $hiddenLocation = $locationService->hideLocation( $location );
 $unhiddenLocation = $locationService->unhideLocation( $hiddenLocation );
 ```
@@ -1088,13 +1088,13 @@ The explanation above is valid for most Repository objects. Modification of prop
 
 Deleting Locations can be done in two ways: delete, or trash. 
 
-``` php:
+``` php
 $locationService->deleteLocation( $locationInfo );
 ```
 
 [`LocationService::deleteLocation()`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/LocationService.html#method_deleteLocation) will permanently delete the Location, as well as all its descendants. Content that has only one Location will be permanently deleted as well. Those with more than one won't be, as they are still referenced by at least one Location.
 
-``` php:
+``` php
 $trashService->trash( $locationInfo );
 ```
 
@@ -1106,7 +1106,7 @@ The `TrashService` can be used to list, restore and delete Locations that were p
 
 This is done using the `ContentService`, by updating the `ContentInfo` with a `ContentUpdateStruct` that sets the new main location:
 
-``` php:
+``` php
 $repository = $this->getContainer()->get( 'ezpublish.api.repository' );
 $contentService = $repository->getContentService();
 $contentInfo = $contentService->loadContentInfo( $contentId );
@@ -1133,7 +1133,7 @@ The Section that a Content item belongs to can be set during creation, using the
 
 **assign section to content**
 
-``` php:
+``` php
 $contentInfo = $contentService->loadContentInfo( $contentId );
 $section = $sectionService->loadSection( $sectionId );
 $sectionService->assignSection( $contentInfo, $section );
@@ -1143,7 +1143,7 @@ This operation involves the `SectionService`, as well as the `ContentService`.
 
 **assign section to content**
 
-``` php:
+``` php
 $contentInfo = $contentService->loadContentInfo( $contentId );
 ```
 
@@ -1151,7 +1151,7 @@ We use `ContentService::loadContentInfo()` to get the Content we want to update
 
 **assign section to content**
 
-``` php:
+``` php
 $section = $sectionService->loadSection( $sectionId );
 ```
 
@@ -1159,7 +1159,7 @@ $section = $sectionService->loadSection( $sectionId );
 
 **assign section to content**
 
-``` php:
+``` php
 $sectionService->assignSection( $contentInfo, $section );
 ```
 
@@ -1177,7 +1177,7 @@ Creating a `ContentType` is actually almost more complex than creating Content.
 
 Let's split the code in three major parts.
 
-``` php:
+``` php
 try
 {
     $contentTypeGroup = $contentTypeService->loadContentTypeGroupByIdentifier( 'content' );
@@ -1211,7 +1211,7 @@ Using the create struct's properties, we can set the Type's properties:
 
 The next big part is to add FieldDefinition objects to our Content Type.
 
-```php:
+```php
 // add a TextLine Field with identifier 'title'
 $titleFieldCreateStruct = $contentTypeService->newFieldDefinitionCreateStruct( 'title', 'ezstring' );
 $titleFieldCreateStruct->names = array( 'eng-GB' => 'Title' );
@@ -1247,7 +1247,7 @@ Each field's properties are set using the create struct's properties:
 
 Once the properties for each create struct are set, the field is added to the Content Type create struct using [`ContentTypeCreateStruct::addFieldDefinition()`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/Values/ContentType/ContentTypeCreateStruct.html#method_addFieldDefinition).
 
-``` php:
+``` php
 try
 {
     $contentTypeDraft = $contentTypeService->createContentType( $contentTypeCreateStruct, array( $contentTypeGroup ) );
diff --git a/docs/api/rest_api_guide.md b/docs/api/rest_api_guide.md
index 5768c0cd5d..5d2a504a81 100644
--- a/docs/api/rest_api_guide.md
+++ b/docs/api/rest_api_guide.md
@@ -59,8 +59,9 @@ Responses returned by the API will also use custom headers to indicate informati
 
 ## Installation
 
-No special preparations are necessary to use the REST API. As long as your eZ Platform is correctly configured, the REST API is available on your site using the URI `/api/ezp/v2/`. If you have installed eZ Platform in a subfolder, prepend the path with this subfolder: http://example.com/**su****b/folder/ezpublish**/api/ezp/v2/.
+No special preparations are necessary to use the REST API. As long as your eZ Platform is correctly configured, the REST API is available on your site using the URI `/api/ezp/v2/`. If you have installed eZ Platform in a subfolder, prepend the path with this subfolder: http://example.com/**sub/folder/ezpublish**/api/ezp/v2/.
 
+!!! note
 Please note that the `/api/ezp/v2` prefix will be used in all REST hrefs, but not in URIs.
 
 ## Configuration
@@ -73,7 +74,7 @@ To enable basic auth based authentication, you need to edit `app/config/security
 
 **security.yml**
 
-```yaml:
+```yaml
 security:
     # ...
     firewalls:
@@ -96,7 +97,7 @@ One of the main reasons for this API is to help implement JavaScript / AJAX inte
 
 **REST API with JavaScript**
 
-```javascript:
+```javascript