Merge branch 'master' into master

docs/3.x.x/en/README.md

@@ -15,10 +15,10 @@ The most advanced open-source Content Management Framework to build powerful API
 
 {% endcenter %}
 
-## v3@alpha.14 is available!
+## v3@alpha.14.2 is available!
 We've been working on a major update for Strapi during the past months, rewriting the core framework and the dashboard.
 
-This documentation is only related to Strapi v3@alpha.14 ([v1 documentation is still available](http://strapi.io/documentation/1.x.x)).
+This documentation is only related to Strapi v3@alpha.14.2 ([v1 documentation is still available](http://strapi.io/documentation/1.x.x)).
 
 **[Get Started](getting-started/installation.md)**<br />
 Learn how to install Strapi and start developing your API.

docs/3.x.x/en/guides/graphql.md

@@ -1,6 +1,6 @@
 # GraphQL
 
-> ⚠️  This feature requires the GraphQL plugin (not installed by default).
+> ⚠️ This feature requires the GraphQL plugin (not installed by default).
 
 ## Usage
 
@@ -10,7 +10,7 @@ To get started with GraphQL in your app, please install the plugin first. To do
 strapi install graphql
 ```
 
-Then, start your app and open your browser at [http://localhost:1337/playground](http://localhost:1337/playground). You should see the interface (GraphQL Playground) that will help you to write GraphQL query to explore your data.
+Then, start your app and open your browser at [http://localhost:1337/graphql](http://localhost:1337/graphql). You should see the interface (GraphQL Playground) that will help you to write GraphQL query to explore your data.
 
 > Install the [ModHeader](https://chrome.google.com/webstore/detail/modheader/idgpnmonknjnojddfkpgkljpfnnfcklj/related) extension to set the `Authorization` header in your request
 
@@ -19,6 +19,7 @@ Then, start your app and open your browser at [http://localhost:1337/playground]
 By default, the [Shadow CRUD](#shadow-crud) feature is enabled and the GraphQL is set to `/graphql`. You can edit these configurations in the following files.
 
 **Path —** `./plugins/graphql/config/settings.json`.
+
 ```
 {
   "endpoint": "/graphql",
@@ -29,7 +30,7 @@ By default, the [Shadow CRUD](#shadow-crud) feature is enabled and the GraphQL i
 
 ### Query API
 
-In the section, we assume that the [Shadow CRUD](#shadow-crud) feature is enabled. For each model, the plugin auto-generates queries which just fit to your needs.
+In the section, we assume that the [Shadow CRUD](#shadow-crud) feature is enabled. For each model, the plugin auto-generates queries and mutations which just fit to your needs.
 
 ##### Fetch a single entry
 
@@ -55,6 +56,118 @@ query {
 }
 ```
 
+##### Create a new entry
+
+- `input`: Object
+  - `data`: Object — Values to insert
+
+```
+mutation {
+  createUser(input: {
+    data: {
+      username: "John",
+      email: "john@doe.com"
+    }
+  }) {
+    user {
+      username
+      email
+    }
+  }
+}
+```
+
+The implementation of the mutations also supports relational attributes. For example, you can create a new `User` and attach many `Post` to it by writing your query like this:
+
+```
+mutation {
+  createUser(input: {
+    data: {
+      username: "John",
+      email: "john@doe.com",
+      posts: ["5b51e3949db573a586ad22de", "5b5b26619b0820c1c2fb79c9"]
+    }
+  }) {
+    user {
+      username
+      email
+      posts {
+        title
+        content
+        publishedAt
+      }
+    }
+  }
+}
+```
+
+##### Update an existing entry
+
+- `input`: Object
+  - `where`: Object - Entry's ID to update
+  - `data`: Object — Values to update
+
+```
+mutation {
+  updateUser(input: {
+    where: {
+      id: "5b28f1747c739e4afb48605c"
+    },
+    data: {
+      username: "John",
+      email: "john@doe.com"
+    }
+  }) {
+    user {
+      username
+      email
+    }
+  }
+}
+```
+
+You can also update relational attributes by passing an ID or an array of IDs (depending of the relationship).
+
+```
+mutation {
+  updatePost(input: {
+    where: {
+      id: "5b5b27f8164f75c29c728110"
+    },
+    data: {
+      author: "5b51e3949db573a586ad22de" // User ID
+    }
+  }) {
+    post {
+      author {
+        username
+        email
+      }
+    }
+  }
+}
+```
+
+##### Delete an entry
+
+- `input`: Object
+  - `where`: Object - Entry's ID to delete
+
+```
+mutation {
+  deleteUser(input: {
+    where: {
+      id: "5b28f1747c739e4afb48605c"
+    }
+  }) {
+    user {
+      username
+      email
+    }
+  }
+}
+```
+
 **Filters**
 
 You can also apply different parameters to the query to make more complex queries.
@@ -73,6 +186,7 @@ You can also apply different parameters to the query to make more complex querie
   - `<field>_containss`: Contains sensitive.
 
 Return the second decade of users which have an email that contains `@strapi.io` ordered by username.
+
 ```
 query {
   users(limit: 10, start: 10, sort: "username:asc", where: {
@@ -85,6 +199,7 @@ query {
 ```
 
 Return the users which have been created after the March, 19th 2018 4:21 pm.
+
 ```
 query {
   users(where: {
@@ -96,17 +211,16 @@ query {
 }
 ```
 
-
 ## Shadow CRUD
 
-To simplify and automate the build of the GraphQL schema, we introduced the Shadow CRUD feature. It automatically generates the type definition, queries and resolvers based on your models. The feature also lets you make complex query with many arguments such as `limit`, `sort`, `start` and `where`.
-
+To simplify and automate the build of the GraphQL schema, we introduced the Shadow CRUD feature. It automatically generates the type definition, queries, mutations and resolvers based on your models. The feature also lets you make complex query with many arguments such as `limit`, `sort`, `start` and `where`.
 
 #### Example
 
 If you've generated an API called `Post` using the CLI `strapi generate:api post` or the administration panel, your model looks like this:
 
 **Path —** `./api/post/models/Post.settings.json`.
+
 ```
 {
   "connection": "default",
@@ -128,7 +242,9 @@ If you've generated an API called `Post` using the CLI `strapi generate:api post
 ```
 
 The generated GraphQL type and queries will be:
+
 ```
+// Post's Type definition
 type Post {
   _id: String
   created_at: String
@@ -138,19 +254,29 @@ type Post {
   published: Boolean
 }
 
+// Queries to retrieve one or multiple posts.
 type Query {
   posts(sort: String, limit: Int, start: Int, where: JSON): [Post]
   post(id: String!): Post
 }
+
+// Mutations to create, update or delete a post.
+type Mutation {
+  createProduct(input: createProductInput): createProductPayload!
+  updateProduct(input: updateProductInput): updateProductPayload!
+  deleteProduct(input: deleteProductInput): deleteProductPayload!
+}
 ```
 
-The query will use the generated controller's actions as resolvers. It means that the `posts` query will execute the `Post.find` action and the `post` query will use the `Post.findOne` action.
+The queries and mutations will use the generated controller's actions as resolvers. It means that the `posts` query will execute the `Post.find` action, the `post` query will use the `Post.findOne` action and the `createProduct` mutation will use the `Post.create` action, etc.
 
 ## Aggregation & Grouping
+
 > This feature is only available on Mongoose ORM.
 
 Strapi now supports Aggregation & Grouping.
 Let's consider again the model mentioned above:
+
 ```
 type Post {
   _id: ID
@@ -161,11 +287,12 @@ type Post {
   nb_likes: Int,
   published: Boolean
 }
-
 ```
+
 Strapi will generate automatically for you the following queries & types:
 
 ### Aggregation
+
 ```
 type PostConnection {
   values: [Post]
@@ -224,6 +351,7 @@ postsConnection {
 ```
 
 Let's say we want to do the same query but for only published posts
+
 ```
 postsConnection(where: { published: true }) {
   aggregate {
@@ -256,6 +384,7 @@ postsConnection {
 ```
 
 Result
+
 ```JSON
 {
   data: {
@@ -294,29 +423,32 @@ Result
 If you want to define a new scalar, input or enum types, this section is for you. To do so, you will have to create a `schema.graphql` file. This file has to be placed into the config folder of each API `./api/*/config/schema.graphql` or plugin `./plugins/*/config/schema.graphql`.
 
 **Structure —** `schema.graphql`.
+
 ```js
 module.exports = {
   definition: ``,
   query: ``,
   type: {},
   resolver: {
-    Query: {}
-  }
+    Query: {},
+  },
 };
 ```
 
 - `definition` (string): let's you define new type, input, etc.
 - `query` (string): where you add custom query.
+- `mutation` (string): where you add custom mutation.
 - `type` (object): allows you to add description, deprecated field or disable the [Shadow CRUD](#shadow-crud) feature on a specific type.
 - `resolver` (object):
   - `Query` (object): let's you define custom resolver, policies for a query.
-
+  - `Mutation` (object): let's you define custom resolver, policies for a mutation.
 
 #### Example
 
 Let say we are using the same previous `Post` model.
 
 **Path —** `./api/post/config/schema.graphql`.
+
 ```js
 module.exports = {
   definition: `
@@ -329,8 +461,11 @@ module.exports = {
     }
   `,
   query: `
-    postsByAuthor(id: String, status: PostStatusInput, limit: Int): [Post]!
+    postsByAuthor(id: ID, status: PostStatusInput, limit: Int): [Post]!
   `,
+  mutation: `
+    attachPostToAuthor(id: ID, authorID: ID): Post!
+  `
   resolver: {
     Query: {
       post: {
@@ -355,6 +490,13 @@ module.exports = {
           return ctx.body.posts || `There is no post.`;
         }
       }
+    },
+    Mutation: {
+      attachPostToAuthor: {
+        description: 'Attach a post to an author',
+        policy: ['plugins.users-permissions.isAuthenticated', 'isOwner'],
+        resolver: 'Post.attachToAuthor'
+      }
     }
   }
 };
@@ -376,7 +518,7 @@ module.exports = {
       age: Int
       children: [Person]
     }
-  `
+  `,
 };
 ```
 
@@ -419,7 +561,7 @@ module.exports = {
 };
 ```
 
->The resolver parameter also accepts an object as a value to target a controller located in a plugin.
+> The resolver parameter also accepts an object as a value to target a controller located in a plugin.
 
 ```js
 module.exports = {
@@ -443,6 +585,7 @@ module.exports = {
 One of the most powerful features of GraphQL is the auto-documentation of the schema. The GraphQL plugin allows you to add a description to a type, a field and a query. You can also deprecate a field or a query.
 
 **Path —** `./api/post/models/Post.settings.json`.
+
 ```
 {
   "connection": "default",
@@ -475,16 +618,24 @@ It might happens that you want to add a description to a query or deprecate it.
 > Remember: The `schema.graphql` file has to be placed into the config folder of each API `./api/*/config/schema.graphql` or plugin `./plugins/*/config/schema.graphql`.
 
 **Path —** `./api/post/config/schema.graphql`.
+
 ```js
 module.exports = {
   resolver: {
     Query: {
       posts: {
         description: 'Return a list of posts', // Add a description to the query.
-        deprecated: 'This query should not be used anymore. Please consider using postsByAuthor instead.' // Deprecate the query and explain the reason why.
-      }
-    }
-  }
+        deprecated:
+          'This query should not be used anymore. Please consider using postsByAuthor instead.', // Deprecate the query and explain the reason why.
+      },
+    },
+    Mutation: {
+      createPost: {
+        description: 'Create a new post',
+        deprecated: 'Please use the dashboard UI instead',
+      },
+    },
+  },
 };
 ```
 
@@ -498,18 +649,30 @@ module.exports = {
     Query: {
       posts: {
         description: 'Return a list of posts',
-        policy: ['plugins.users-permissions.isAuthenticated', 'isOwner', 'global.logging']
-      }
-    }
-  }
+        policy: [
+          'plugins.users-permissions.isAuthenticated',
+          'isOwner',
+          'global.logging',
+        ],
+      },
+    },
+    Mutation: {
+      createPost: {
+        description: 'Create a new post',
+        policy: ['plugins.users-permissions.isAuthenticated', 'global.logging'],
+      },
+    },
+  },
 };
 ```
 
 In this example, the policy `isAuthenticated` located in `./plugins/users-permissions/config/policies/isAuthenticated.js` will be executed first. Then, the `isOwner` policy located in the `Post` API `./api/post/config/policies/isOwner.js`. Next, it will execute the `logging` policy located in `./config/policies/logging.js`. Finally, the resolver will be executed.
 
+The same process is applied to the `createPost` mutation.
+
 > Note: There is no custom resolver in that case, so it will execute the default resolver (Post.find) provided by the Shadow CRUD feature.
 
-### Link a query to a controller action
+### Link a query or mutation to a controller action
 
 By default, the plugin will execute the actions located in the controllers that has been generated via the Content-Type Builder plugin or the CLI. For example, the query `posts` is going to execute the logic inside the `find` action in the `Post.js` controller. It might happens that you want to execute another action or a custom logic for one of your query.
 
@@ -519,10 +682,16 @@ module.exports = {
     Query: {
       posts: {
         description: 'Return a list of posts by author',
-        resolver: 'Post.findByAuthor'
-      }
-    }
-  }
+        resolver: 'Post.findByAuthor',
+      },
+    },
+    Mutation: {
+      createPost: {
+        description: 'Create a new post',
+        resolver: 'Post.customCreate',
+      },
+    },
+  },
 };
 ```
 
@@ -530,6 +699,10 @@ In this example, it will execute the `findByAuthor` action of the `Post` control
 
 > Note: The `obj` parameter is available via `ctx.params` and the `options` are available via `ctx.query` in the controller's action.
 
+The same process is also applied for the `createPost` mutation. It will execute the `customCreate` action of the `Post` controller.
+
+> Note: The `where` parameter is available via `ctx.params` and the `data` are available via `ctx.request.body` in the controller's action.
+
 ### Define a custom resolver
 
 ```js
@@ -538,7 +711,7 @@ module.exports = {
     Query: {
       posts: {
         description: 'Return a list of posts by author',
-        resolver: (obj, options, context) => {
+        resolver: (obj, options, { context }) => {
           // You can return a raw JSON object or a promise.
 
           return [{
@@ -547,6 +720,19 @@ module.exports = {
           }];
         }
       }
+    },
+    Mutation: {
+      updatePost: {
+        description: 'Update an existing post',
+        resolver: (obj, options, { context }) => {
+          // The `where` and `data` parameters passed as arguments
+          // of the GraphQL mutation are available via the `context` object.
+          const where = context.params;
+          const data = context.request.body;
+
+          return await strapi.api.post.services.post.addPost(data, where);
+        }
+      }
     }
   }
 };
@@ -574,6 +760,18 @@ module.exports = {
           }];
         }
       }
+    },
+    Mutation: {
+      updatePost: {
+        description: 'Update an existing post',
+        resolverOf: 'Post.update', // Will apply the same policy on the custom resolver than the controller's action `update` located in `Post.js`.
+        resolver: (obj, options, { context }) => {
+          const where = context.params;
+          const data = context.request.body;
+
+          return await strapi.api.post.services.post.addPost(data, where);
+        }
+      }
     }
   }
 };
@@ -586,11 +784,15 @@ To do that, we need to use the `schema.graphql` like below:
 ```js
 module.exports = {
   type: {
-    Post: false // The Post type won't be "queriable".
+    Post: false // The Post type won't be "queriable" or "mutable".
   }
   resolver: {
     Query: {
       posts: false // The `posts` query will no longer be in the GraphQL schema.
+    },
+    Mutation: {
+      createPost: false,
+      deletePOst: false
     }
   }
 };

docs/3.x.x/en/guides/i18n.md

@@ -60,3 +60,17 @@ You need to define the english and french translation for this key.
 ```
 
 That's all! The request `GET /hello/John?locale=en_US` will return `Hello John` and `GET /hello/Tom?locale=fr_FR` will return `Bonjour Tom`.
+
+## Content Internationalization
+
+Translating content from a language to another has been requested by many of you. As you may have seen on our website, the [Internationalization plugin](https://strapi.io/marketplace/internationalization) is not available yet because we need to go out of alpha before developing new plugins.
+
+But, no worries, we have a good **work around to help you internationalize your content**!
+
+The solution is simple: **suffix your fields**.
+
+For example if you are building a blog with posts, you may have a Content Type `post` with two fields: `title` and `content`. To make them available in english and french for example, simply replace them by `title_en`, `title_fr`, `content_en` and `content_fr`.
+
+Then, when you request your API, you will get all these fields in your response payload. If you want to select only some of them (in a specific language) we recommend you to use the [GraphQL plugin](graphql.md).
+
+![Content Internationalization Strapi](../assets/internationalization.gif)

package.json

@@ -1,6 +1,6 @@
 {
   "private": true,
-  "version": "3.0.0-alpha.14.1.1",
+  "version": "3.0.0-alpha.14.2",
   "dependencies": {},
   "devDependencies": {
     "assert": "~1.3.0",