Merge branch '2.3'

Author: dunglas

.travis.yml

@@ -4,28 +4,26 @@ node_js:
 
 cache:
   yarn: true
+  directories:
+    - $HOME/.cache/pip
 
 env:
   global:
     secure: gjiWHIgNjLXuEFmLiepiOTHOuauHfeKHutrE0sBwFZUQzP9FoGTZzJub1z8/vm+hhygA+TZbB0iclygHyNrXCkZyNdnZXChXl4iPdYqY3OARPOAbQff16+/XSUDsZ/Ok1etdb3kKor1R4rBt/WywBvXmmdggumTA3yT5ExI+dyomdONo4yMUZ7g1la0ehMEzGqyVjt0nUW31PN3l6dI1qgigHCuotSrrpWP6fTXuUh5l6YA7KXb/V1hJxaGENLz1Cdfk0sF66e4KsV/DX6JZSqpvdqVB8OTPU+si511yJtGS8OeuLs4RqmXMLrY/ChCodlYnfCE+NleBFpUnCVqth/RDRh7LvplUJlpsXNcfyoA3mOFmZa0euOMCqJ3qwESz802Y9c5oN63hn2OUF/raFDc3SMMC86FFHxwyYjz5+yzXYupnFNj39NKdQ1v1KBbY8BD8UT8RU3mlu4/3LRz0tSamREHj3pGgBmvgUZfUE1dMngeaZjOmBaIZH8TnKQ75CvfnoT+LJnZo6g9g4uwz6jtaIziSMZ0OW/95nF8yx+xONbHEtt5ex5M09NOFsN2vB2bcUAgIjyGrmmNLQadwJyQv557IGPEE5CyGhJpXh9XZ+WMw2vO45MOw4sQPkARF6OJkMteqFc2NLXMOQJ07EScbgEKR/9VOcyxIk/7a7nc=
 
-before_install:
-  - curl -o- -L https://yarnpkg.com/install.sh | bash
-  - export PATH="$HOME/.yarn/bin:$PATH"
-
 install:
-  - pip install --user proselint
+  - pip install --quiet --user proselint
   - cp .proselintrc ~
   - cd ..
-  - git clone https://github.com/api-platform/website.git
+  - git clone --depth 1 https://github.com/api-platform/website.git
   - cd website
-  - yarn install
+  - yarn install --silent
   - ln -s $TRAVIS_BUILD_DIR src/pages/docs
   - cd $TRAVIS_BUILD_DIR
 
 script:
-  - find . -name '*.md' ! -name 'conduct.md' ! -name 'heroku.md' -exec proselint {} \;
-  - cd $TRAVIS_BUILD_DIR/../website
+  - find . -name '*.md' -exec proselint {} \;
+  - cd ../website
   - bin/generate-nav
   - GATSBY_BRANCH_NAME=$TRAVIS_BRANCH yarn gatsby build
   # Preserve artifacts

admin/getting-started.md

@@ -5,7 +5,7 @@
 Install the skeleton and the library:
 
 Start by installing [the Yarn package manager](https://yarnpkg.com/) ([NPM](https://www.npmjs.com/) is also supported) and
-the [Create React App](https://github.com/facebookincubator/create-react-app) tool.
+the [Create React App](https://facebook.github.io/create-react-app/) tool.
 
 Then, create a new React application for your admin:
 
@@ -58,7 +58,7 @@ Clear the cache to apply this change:
 
 Your new administration interface is ready! Type `yarn start` to try it!
 
-Note: if you don't want to hardcode the API URL, you can [use an environment variable](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#adding-custom-environment-variables).
+Note: if you don't want to hardcode the API URL, you can [use an environment variable](https://facebook.github.io/create-react-app/docs/adding-custom-environment-variables).
 
 ## Customizing the Admin
 
@@ -145,7 +145,7 @@ const myApiDocumentationParser = entrypoint => parseHydraDocumentation(entrypoin
               src: value
             });
 
-            field.fieldComponent = (
+            field.field = (
               <FunctionField
                 key={field.name}
                 render={
@@ -157,7 +157,7 @@ const myApiDocumentationParser = entrypoint => parseHydraDocumentation(entrypoin
               />
             );
 
-            field.inputComponent = (
+            field.input = (
               <ImageInput accept="image/*" key={field.name} multiple={false} source={field.name}>
                 <ImageField source="src"/>
               </ImageInput>

admin/handling-relations-to-collections.md

@@ -71,8 +71,6 @@ class Book
 
 The admin handles this `to-many` relation automatically!
 
-But we can go further:
-
 ## Customizing a Property
 
 Let's customize the components used for the `authors` property, to display them by their 'name' instead 'id' (the default behavior).

client-generator/index.md

@@ -1,6 +1,6 @@
 # The API Platform Client Generator
 
-Client Generator is the fastest way to scaffold fully-featured webapps and native mobile apps from APIs supporting the [Hydra](http://www.hydra-cg.com/) format.
+Client Generator is the fastest way to scaffold fully featured webapps and native mobile apps from APIs supporting the [Hydra](http://www.hydra-cg.com/) format.
 
 ![Screencast](images/client-generator-demo.gif)
 

core/deprecations.md

@@ -0,0 +1,97 @@
+# Deprecating Resources and Properties (Alternative to Versioning)
+
+A best practice regarding web APIs development is to apply [the evolution strategy](https://philsturgeon.uk/api/2018/05/02/api-evolution-for-rest-http-apis/)
+to indicate to client applications which resource types, operations and fields are deprecated and shouldn't be used anymore.
+
+While versioning an API requires modifying all clients to upgrade, even the ones not impacted by the changes.
+It's a tedious task that should be avoided as much as possible.
+
+On the other hand, the evolution strategy (also known as versionless APIs) consists of deprecating the fields, resources
+types or operations that will be removed at some point.
+
+Most modern API formats including [JSON-LD / Hydra](content-negotiation.md), [GraphQL](graphql.md) and [OpenAPI](swagger.md)
+allow to mark resources types, operations or fields as deprecated.
+
+## Deprecating Resource Classes, Operations and Properties
+
+When using API Platform, it's easy to mark a whole resource, a specific operation or a specific property as deprecated.
+All documentation formats mentioned in the introduction will then automatically take the deprecation into account.
+
+To deprecate a resource class, use the `deprecationReason` attribute:
+
+```php
+<?php
+// api/src/Entity/Parchment.php
+
+namespace App\Entity;
+
+use ApiPlatform\Core\Annotation\ApiResource;
+
+/**
+ * @ApiResource(deprecationReason="Create a Book instead")
+ */
+class Parchment
+{
+    // ...
+}
+```
+
+As you can see, to deprecate a resource, we just have to explain what the client should do to upgrade in the dedicated attribute.
+
+The deprecation will automatically be taken into account by clients supporting the previously mentioned format, including
+[API Platform Admin](../admin/index.md), [API Platform Client Generator](../client-generator/index.md) and the lower level
+[api-doc-parser library](https://github.com/api-platform/api-doc-parser).
+
+Here is how it renders for OpenAPI in the built-in Swagger UI shipped with the framework:
+
+![Deprecation shown in Swagger UI](images/deprecated-swagger-ui.png)
+
+And now in the built-in version of GraphiQL (for GraphQL APIs):
+
+![Deprecation shown in GraphiQL](images/deprecated-graphiql.png)
+
+You can also use this new `deprecationReason` attribute to deprecate specific [operations](operations.md):
+
+```php
+<?php
+// api/src/Entity/Review.php
+
+/**
+ * @ApiResource(itemOperations={
+ *     "get"={"deprecation_reason"="Retrieve a Book instead"}
+ * })
+ */
+class Parchment
+{
+    // ...
+}
+```
+
+It's also possible to deprecate a single property:
+
+```php
+<?php
+// api/src/Entity/Review.php
+
+namespace App\Entity;
+
+use ApiPlatform\Core\Annotation\ApiProperty;
+use ApiPlatform\Core\Annotation\ApiResource;
+
+/**
+ * @ApiResource
+ */
+class Review
+{
+    // ...
+
+    /**
+     * @ApiProperty(deprecationReason="Use the rating property instead")
+     */
+    public $letter;
+}
+```
+
+* With JSON-lD / Hydra, [an `owl:deprecated` annotation property](https://www.w3.org/TR/owl2-syntax/#Annotation_Properties) will be added to the appropriate data structure
+* With Swagger / OpenAPI, [a `deprecated` property](https://swagger.io/docs/specification/2-0/paths-and-operations/) will be added
+* With GraphQL, the [`isDeprecated` and `deprecationReason` properties](https://facebook.github.io/graphql/June2018/#sec-Deprecation) will be added to the schema

core/file-upload.md

@@ -249,5 +249,5 @@ uploaded cover, you can have a nice illustrated book record!
 }
 ```
 
-Voila! You can now send files to your API, and link them to any other resources
+Voilà! You can now send files to your API, and link them to any other resources
 in your app.

core/fosuser-bundle.md

@@ -22,7 +22,7 @@ If you are using the API Platform Standard Edition, you will need to enable the
 configuration options:
 
 ```yaml
-# api/config/packages/api_platform.yaml
+# api/config/packages/framework.yaml
 framework:
     form: { enabled: true }
 ```

core/images/deprecated-graphiql.png

@@ -58,7 +58,7 @@ all set!
 
 It is simple to specify what groups to use in the API system:
 
-1. Add the `normalizationContext` and `denormalizationContext` annotation properties to the `@ApiResource` annotation, and specify which groups to use. Here you see that we add `read` and `write`, respectively.  You can use any group names you wish.
+1. Add the `normalizationContext` and `denormalizationContext` annotation properties to the `@ApiResource` annotation, and specify which groups to use. Here you see that we add `read` and `write`, respectively. You can use any group names you wish.
 2. Apply the `@Groups` annotation to properties in the object.
 
 ```php
@@ -129,7 +129,7 @@ App\Entity\Book:
 ```
 
 In the previous example, the `name` property will be visible when reading (`GET`) the object, and it will also be available
-to write (`PUT/POST`).  The `author` property will be write-only; it will not be visible when serialized responses are 
+to write (`PUT/POST`). The `author` property will be write-only; it will not be visible when serialized responses are 
 returned by the API.
 
 Internally, API Platform passes the value of the `normalization_context` to the Symfony Serializer during the normalization
@@ -415,7 +415,7 @@ final class BookContextBuilder implements SerializerContextBuilderInterface
 ```
 
 If the user has the `ROLE_ADMIN` permission and the subject is an instance of Book, `admin_input` group will be dynamically added to the 
-denormalization context.  The `$normalization` variable lets you check whether the context is for normalization (if `TRUE`) or denormalization 
+denormalization context. The `$normalization` variable lets you check whether the context is for normalization (if `TRUE`) or denormalization 
 (`FALSE`).
 
 ## Changing the Serialization Context on a Per-item Basis
@@ -500,8 +500,8 @@ class BookAttributeNormalizer implements ContextAwareNormalizerInterface, Normal
 This will add the serialization group `can_retrieve_book` only if the currently logged-in user has access to the given book 
 instance.
 
-Note: In this example, we use the `TokenStorageInterface` to verify access to the book instance.  However, Symfony 
-provides many useful other services that might be better suited to your use case.  For example, the [`AuthorizationChecker`](https://symfony.com/doc/current/components/security/authorization.html#authorization-checker).
+Note: In this example, we use the `TokenStorageInterface` to verify access to the book instance. However, Symfony 
+provides many useful other services that might be better suited to your use case. For example, the [`AuthorizationChecker`](https://symfony.com/doc/current/components/security/authorization.html#authorization-checker).
 
 ## Name Conversion
 
@@ -524,7 +524,7 @@ api_platform:
 
 ## Decorating a Serializer and Adding Extra Data
 
-In the following example, we will see how we add extra informations to the serialized output.  Here is how we add the 
+In the following example, we will see how we add extra informations to the serialized output. Here is how we add the 
 date on each request in `GET`:
 
 ```yaml
@@ -599,7 +599,7 @@ API Platform is able to guess the entity identifier using [Doctrine metadata](ht
 It also supports composite identifiers.
 
 If you are not using the Doctrine ORM Provider, you must explicitly mark the identifier using the `identifier` attribute of
-the `ApiPlatform\Core\Annotation\ApiProperty` annotation.  For example:
+the `ApiPlatform\Core\Annotation\ApiProperty` annotation. For example:
 
 
 ```php
@@ -644,7 +644,7 @@ App\Entity\Book:
 ```
 
 In some cases, you will want to set the identifier of a resource from the client (e.g. a client-side generated UUID, or a slug).
-In such cases, you must make the identifier property a writable class property.  Specifically, to use client-generated IDs, you 
+In such cases, you must make the identifier property a writable class property. Specifically, to use client-generated IDs, you 
 must do the following:
 
 1. create a setter for the identifier of the entity (e.g. `public function setId(string $id)`) or make it a `public` property ,

core/images/deprecated-swagger-ui.png

@@ -83,7 +83,7 @@ Before running your application for the first time, be sure to create the databa
 
 ## Tiller RBAC Issue
 
-We noticed that some tiller RBAC trouble occured, you generally can resolve it running:
+We noticed that some tiller RBAC trouble occurred, you generally can resolve it running:
 
     kubectl create serviceaccount --namespace kube-system tiller
       serviceaccount "tiller" created

core/serialization.md

@@ -6,7 +6,7 @@
 > - Fabien Potencier (creator of Symfony), SymfonyCon 2017
 
 [API Platform](https://api-platform.com) is a powerful but easy to use **full stack** framework dedicated to API-driven projects.
-It contains a **PHP** library to create fully-featured APIs supporting industry-leading standards (JSON-LD, GraphQL, OpenAPI...),
+It contains a **PHP** library to create fully featured APIs supporting industry-leading standards (JSON-LD, GraphQL, OpenAPI...),
 provides ambitious **JavaScript** tooling to consume those APIs in a snap (admin, PWA and mobile apps generators, hypermedia
 client...) and is shipped with a nice **Docker** and **Kubernetes** integration to develop and deploy instantly in the cloud.
 
@@ -510,7 +510,7 @@ Now try to add another book by issuing a `POST` request to `/books` with the fol
 }
 ```
 
-Oops, we missed to add the title. But submit the request anyway. You should get a 500 error with the following message:
+Oops, we missed to add the title. Submit the request anyway, you should get a 500 error with the following message:
 
     An exception occurred while executing 'INSERT INTO book [...] VALUES [...]' with params [...]:
     SQLSTATE[23000]: Integrity constraint violation: 1048 Column 'title' cannot be null