998-Documentation-Améliorer-la-page-de-l'API-GraphQL

docs/src/en/api-graphql.md

@@ -2,40 +2,142 @@
 title: "API GraphQL"
 ---
 
-## Setting up your GraphQl query
+## Stylo's GraphQL API - An introduction
 
-Stylo now incorporates a GraphQL API that users can read and write to.
+Stylo now incorporates a GraphQL API to which users can read and write.
 
 The API provides access to Stylo data via the GraphQL query language.
 From the endpoint [https://stylo.huma-num.fr/graphql](https://stylo.huma-num.fr/graphql), you can connect Stylo to a whole range of customized functionalities.
 For example, the API allows you to retrieve your articles and integrate them into your favorite static site generator.
 
-To execute a request, you must first retrieve your *APIkeys* from your Stylo account settings.
-Your user account settings can be found in the drop-down menu that appears when you click on your username at the top of the interface.
+GraphQL stands for **Graph Query Language**. It's a query language and runtime environment for application programming interfaces (APIs). It was first created by Facebook in 2012, and released as open source in 2015. You get only the data you need from your queries, and you define their structure.
 
-The user key for API configuration can be found in the second section of the account parameters under the entry `API Key`.
-A button allows you to copy the entire key to the clipboard.
+### Why use GraphQL?
 
-Then you can write your query in your preferred environment (e.g. [GraphQL Playground](https://github.com/graphql/graphql-playground)) and start playing with your Stylo data.
-If you're using GraphQL Playground, the API self-documents directly in your interface.
-You'll have access to all the queries and parameters you can use in just a few clicks.
+- This environment is very easy to use. 
+- It lets you visualize and manipulate your data in Stylo. 
+- You get exactly what you ask for, and no more. You can have several types of data in a single request. 
+- And it's fast.
+- You don't need to know how to code to use this environment, as the available requests are listed in the documentation.
 
-Here's an example of a query to retrieve all your items:
+### Before you start
 
-```graphql
-query tousMesArticles {
-  user {
-    _id
-    email
-
-    articles {
+1. Install GraphQL
+
+If you're using Google Chrome, it's easy to install the extension. You can choose, for example, GraphQL Playground or Altair GraphQL. If you want to install it on your computer and you have brew, you can also enter the command "brew cask install graphql-playground". There are a number of options available to you, and if these don't suit you, you can search for others - these are just a few suggestions. 
+
+For this course, we'll be using the GraphQL Playground extension, but you can also use the local version or the [web version](https://legacy.graphqlbin.com/new).
+
+2. Enter the URL
+
+Once you've installed the extension or environment, make sure you enter the URL in the field provided above, i.e. https://stylo.huma-num.fr/graphql. This is the API endpoint.
+
+3. API key
+
+You also need to enter your API key. In the Stylo application, click on your name, the drop-down menu will open and then you click on your e-mail address. This will take you to your account information. This is where you'll find your key. Copy it. Back in GraphQL, on the bottom left is the "HTTP HEADERS" tab. Enter the key as follows: 
+
+```
+{
+"Authorization": "YOUR API KEY" 
+}
+```
+
+Make sure you are in the "HTTP HEADERS" tab.
+
+![Getting started with GraphQL](https://upload.wikimedia.org/wikipedia/commons/2/22/Capture_d%E2%80%99%C3%A9cran_2024-01-23_181249.png)
+
+Now you're ready to enter your first query!
+
+## Getting started
+
+In this introduction to Stylo's GraphQL API, we'll look at how to use queries and mutations. Queries let you visualize the data available in Stylo, while mutations let you manipulate, create or delete data.
+
+### Queries
+
+Simply request a query. This is the first word in your request. 
+In the first example, we're asking for a list of all your articles contained in Stylo. In square brackets, we specify what other information we'd like to have. In this case, we'd like to know the associated user, the title of the article and its identifier. 
+
+You can, of course, request other information as well. The possibilities are immense, and they go hand in hand with your needs. 
+Don't forget to close the brackets after opening each one.When you're ready, click the execute button. 
+
+```
+Example 1:
+query allMyArticles {
+    user {
+     _id
+     email
+
+     articles {
       _id
       title
+      }
+   }
+}
+```
+
+In example 2, you need to enter the identifier of one of the articles in the previous list. Keep it, as you'll need it for the last example too. Once you've entered the query, you should see the title of your item, as well as the person who owns it.
+
+``` 
+Example 2:
+query articles {
+    article(article: "ARTICLE ID"){
+    title
+       owner {
+    displayName
+    username
+    email
     }
-  }
 }
+}
+```
+
+For this last example, once again you need to enter your article ID in the appropriate space. This time, GraphQL shows you not only the title of your article and the contributors, but also the Markdown, Yaml and BibTex it contains! 
+
 ```
+Example 3 :
+query {
+    article(article: "ARTICLE ID"){
+    title
+    contributors{user{displayName}}
+    workingVersion{md yaml bib}
+    }
+}
+
+```
+
+You may have noticed that the application offers you autocompletion options as you write. This gives you examples of what you can ask for later. 
+
+You'll also find a complete list in the tab to the left of the screen called "Schema" . If you click on it, the tab opens. 
+The API documentation tab is one of GraphQL Playground's most interesting features. It lets you preview all possible queries and mutations, along with their details in a single field of a given schema.
+
+![Schema](https://upload.wikimedia.org/wikipedia/commons/c/c6/Capture_d%E2%80%99%C3%A9cran_2024-01-23_184801.png)
+
+
+### Mutations
+
+In addition to queries, you can also use mutations in the interface. 
+What are mutations? Mutations are another form of query. However, all operations that cause writes must be sent explicitly via a mutation. Put simply, while queries allow you to view your data, mutations are used to create, modify or delete data or content. 
+
+Let's take a look at the list in the "Schema" tab: ![Mutations](https://upload.wikimedia.org/wikipedia/commons/4/48/Capture_d%E2%80%99%C3%A9cran_2024-01-23_191722.png)
+
+You can create articles, share your articles, duplicate them and much more. The list goes on and on.
+
+Let's look at an example of a mutation: 
+
+
+```
+mutation{createArticle(title: "ARTICLE TITLE",
+    user:" YOUR ID ")
+    {title _id}}
+
+```
+
+In this example, we're asking the API to create an article for us. To do this, enter your ID number, which you'll find either in your Stylo account information or which you can request in GraphQL Playground. Then enter the title you want in the appropriate space. Once the mutation has been launched, return to Stylo's "Articles" page and you'll see your new article with the chosen title. 
+
+## Finally
+
+GraphQL Playground is like a sandbox, an integrated development environment (IDE) where you can create scripts in any language. These scripts integrate GraphQL queries to automate certain tasks: for example, we could imagine a local backup of Stylo data!
 
-## Examples and applications
+As you can see, Stylo's GraphQL API is easy to use. All you have to do is enter the name of the data you want, or the mutations you want, and the application gives them to you. That's all there is to it, and all that's left is for you to try out different queries and mutations for yourself!
 
-Coming soon.
+More advanced training to come...

docs/src/fr/api-graphql.md

@@ -2,41 +2,141 @@
 title: API GraphQL
 ---
 
-## Configurer sa requête GraphQL
+## API GraphQL de Stylo - Une introduction
 
 Stylo intègre dorénavant une API GraphQL à laquelle les utilisateurs peuvent avoir accès en lecture et en écriture.
 
 L'API donne accès aux données de Stylo grâce au langage de requête GraphQL.
-Depuis l'*endpoint* [https://stylo.huma-num.fr/graphql](https://stylo.huma-num.fr/graphql), il devient possible de connecter Stylo à tout un ensemble de fonctionnalités réalisées par vos soins, donc sur mesure.
+Depuis l'*endpoint* https://stylo.huma-num.fr/graphql, il devient possible de connecter Stylo à tout un ensemble de fonctionnalités réalisées par vos soins, donc sur mesure.
 Par exemple, l'API vous permet de récupérer vos articles et de les intégrer dans votre générateur de site statique préféré.
 
-Pour exécuter une requête, vous devez tout d'abord récupérer votre *APIkeys* dans les paramètres de votre compte Stylo.
-Les paramètres de votre compte utilisateur se trouvent dans le menu déroulant qui apparaît lorsque vous cliquez sur votre nom d'utilisateur en haut de l'interface.
+GraphQL signifie **Graph Query Language**. C'est un langage de requête et un environnement d'exécution pour les interfaces de programmation d'application (API). C'est tout d'abord une création de Facebook en 2012, qui fut publié en libre accès en 2015. Vous obtenez de vos requêtes uniquement les données demandées et vous en définissez la structure.
 
+### Pourquoi utiliser GraphQL?
 
-La clef utilisateur pour la configuration de l'API se trouve dans la deuxième section des paramètres du compte sous l'entrée `API Key`.
-Un bouton permet de copier l'intégralité de la clef dans le presse-papier.
+- Cet environnement est très simple d'utilisation. 
+- Elle vous permet de visualiser et de manipuler vos données contenues dans Stylo. 
+- Vous obtenez exactement ce que vous demandez et pas plus. Vous pouvez ainsi avoir plusieurs types de données dans une seule demande. 
+- C'est rapide.
+- L'environnement ne requiert pas de savoir coder, les demandes disponibles sont présentes dans la documentation.
 
-Ensuite, vous pouvez écrire votre requête dans votre environnement préféré (ex: [GraphQL Playground](https://github.com/graphql/graphql-playground)) et commencer à jouer avec vos données Stylo.
-Si vous utilisez GraphQL Playground, l'API s'auto-documente directement dans votre interface.
-Vous accéderez à l'ensemble des requêtes et paramètres utilisables en seulement quelques clics.
+### Avant de commencer
 
-Voici un exemple de requête pour récupérer tous vos articles : 
+1. Installer GraphQL
 
-```graphql
+Pour l'installation, vous pouvez vous référer au site...?
+
+
+2. Entrer l'URL
+
+Une fois l'extension ou l'environnement installé, assurez-vous d'entrer dans le champ de l'URL, celle fournie plus haut, soit https://stylo.huma-num.fr/graphql. C'est l'endpoint de l'API.
+
+3. Clé API
+
+Il vous faut aussi entrer votre clé API. Dans l'application Stylo, cliquez sur votre nom, le menu déroulant s'ouvrira et vous cliquez ensuite sur votre adresse courriel. Cela vous mènera aux informations de votre compte. C'est dans cette section que vous trouverez votre clé. Copiez-la. De retour dans GraphQL, en bas à gauche se trouve l'onglet "HTTP HEADERS". Entrez la clé comme suis : 
+
+```
+{
+"Authorization":"VOTRE CLÉ API" 
+}
+```
+
+Assurez-vous d'être bien dans l'onglet "HTTP HEADERS".
+
+![Commencer avec GraphQL](https://upload.wikimedia.org/wikipedia/commons/2/22/Capture_d%E2%80%99%C3%A9cran_2024-01-23_181249.png)
+
+Vous êtes maintenant prêt à entrer votre première requête!
+
+
+## Pour commencer
+
+Dans cette initiation à l'API GraphQL de Stylo, nous verrons comment utiliser les requêtes et les mutations. Les requêtes vous permettront de visualiser vos données disponibles dans Stylo et les mutations vous permettront de les manipuler, d'en créer ou de les supprimer.
+
+### Les requêtes
+
+Il suffit de demander une requête (Query). C'est le premier mot de votre demande. 
+Ensuite, il faut spécifier le type de requête, dans le premier exemple, nous lui demandons une liste de tous vos articles contenus dans Stylo. Entre crochets, nous spécifions quelles autres informations nous aimerions avoir. Dans ce cas, nous voulons savoir quel est l'utilisateur associé, le titre de l'article, ainsi que son identifiant. 
+
+Vous pouvez bien sûr demander d'autres informations. Les possibilités sont immenses et vont de pair avec vos besoins. 
+Il ne faut pas oublier de refermer les crochets après l'ouverture de chacun. Quand vous êtes prêts cliquez sur le bouton d'exécution. 
+
+```
+Exemple 1 :
 query tousMesArticles {
-  user {
-    _id
-    email
-
-    articles {
+    user {
+     _id
+     email
+     
+     articles {
       _id
       title
+      }
+   }
+}
+```
+
+Dans l'exemple 2, il vous faut entrer l'identifiant de l'un des article de la liste précédente. Gardez-le, vous en aurez aussi besoin pour le dernier exemple. Une fois la requête entrée, vous devriez voir le titre de votre article, ainsi que la personne qui le détient.
+
+``` 
+Exemple 2 :
+query articles {
+    article(article: " ID DE L'ARTICLE "){
+    title
+       owner {
+    displayName
+    username
+    email
     }
-  }
+}
 }
 ```
 
-## Exemples et applications
+Pour ce dernier exemple, il vous faut encore une fois entrer votre identifiant d'article dans l'espace approprié. Cette fois-ci, GraphQL vous montre le titre de votre article, ceux qui y ont contribué, mais aussi le Markdown, Yaml et BibTex qu'il contient! 
+
+```
+Exemple 3 :
+query {
+    article(article: " ID DE L'ARTICLE "){
+    title
+    contributors{user{displayName}}
+    workingVersion{md yaml bib}
+    }
+}
+
+```
+
+Vous aurez peut-être remarqué que l'application vous offre des options d'autocomplétions lorsque vous écrivez. Cela vous donne des exemples de ce que vous pouvez demander par la suite. 
+
+Vous trouverez aussi une liste complète dans l'onglet à gauche de l'écran « Schema » ou dans certaines version « Doc ». Si vous cliquez dessus, l'onglet s'ouvre. 
+L'onglet de documentation de l'API est une fonctionnalités très intéressantes de GraphQL Playground. Il vous permet de prévisualiser toutes les requêtes et mutations possibles, ainsi que leurs détails en un seul champ d'un schéma donné.
+
+![Schema](https://upload.wikimedia.org/wikipedia/commons/c/c6/Capture_d%E2%80%99%C3%A9cran_2024-01-23_184801.png)
+
+
+### Les mutations
+
+En plus des requêtes, vous pouvez aussi utiliser des mutations dans l'interface. 
+Qu'est-ce que c'est? Les mutations sont une autre forme de requête. Cependant, toutes les opérations qui provoquent des écritures doivent être envoyées explicitement via une mutation. Pour faire simple, alors que les requêtes vous permettent de voir vos données, les mutations servent à créer, modifier ou supprimer des données ou du contenu. 
+
+Regardons la liste dans l'onglet "Schema" : ![Mutations](https://upload.wikimedia.org/wikipedia/commons/4/48/Capture_d%E2%80%99%C3%A9cran_2024-01-23_191722.png)
+
+Vous pouvez créer des articles, partager vos articles, les dupliquer et plus encore. La liste est longue.
+
+Regardons un exemple de mutation : 
+
+```
+mutation{createArticle(title:"TITRE DE L'ARTICLE",
+    user:" VOTRE ID ")
+    {title _id}}
+
+```
+
+Dans cet exemple, nous demandons à l'API de nous créer un article. Pour ce faire entrer votre numéro d'identification que vous trouverez soit dans les informations de votre compte Stylo ou que vous pouvez demander dans GraphQL Playground. Entrez ensuite le titre que vous voulez dans l'espace approprié. Une fois la mutation lancée, retournez sur la page « Articles » de Stylo et vous verrez votre nouvel article avec le titre choisi. 
+
+## Pour finir
+
+GraphQL Playground est tel un bac-à-sable, c'est-à-dire un environnement de développement intégré (IDE) où il est possible de créer des scripts, quel que soit le langage utilisé. Ces scripts intègrent des requêtes GraphQL pour automatiser certaines tâches : par exemple, on pourrait imaginer une sauvegarde en local des données de Stylo!
+
+Comme vous avez pu voir, l'API GraphQL de Stylo est simple à utiliser. Il suffit de d'entrer le nom des données souhaitées ou les mutations voulues et l'application vous les donne. La formation se termine ici, il ne vous reste plus qu'à essayer différentes requêtes et mutations par vous-mêmes!
 
-À venir.
+Formation plus avancée à venir...