docs(client-integration): introduce documentation

Author: vinceAmstoutz

core/client-integration.md

@@ -0,0 +1,137 @@
+# Client Integrations
+
+## Edge Side API (ESA)
+
+> [Edge Side APIs (ESA)](https://edge-side-api.rocks/) is an architectural pattern that allows the creation of more
+> reliable, efficient, and less resource-intensive APIs. It revives the core REST/HATEOAS principles while taking full
+> advantage of the new capabilities provided by the web platform.
+>
+> ESA promotes a mixed approach (synchronous and asynchronous), offering simplicity in development and use, exceptional
+> performance, and the ability for clients to receive real-time updates of the resources they fetched. ESA also leverages
+> existing standards to expose API documentation, enabling the creation of generic clients capable of discovering the
+> API’s capabilities at runtime.
+>
+> — *From [ESA White Paper](https://edge-side-api.rocks/white-paper)*
+
+## JavaScript Client Integrations
+
+API Platform offers a suite of tools and libraries that streamline the integration of JavaScript clients with APIs.
+These tools simplify development by automating tasks such as data fetching, administration panel creation,
+and real-time updates. Below is a detailed overview of the available clients, libraries, and their usage.
+
+### Clients and Tools Overview
+
+#### Admin
+
+API Platform Admin is a dynamic administration panel generator built with React Admin. It automatically adapts to your
+API schema and provides extensive customization options.
+
+[Learn more about API Platform Admin](../admin/index.md).
+
+#### Create Client
+
+The Client Generator creates JavaScript/TypeScript clients based on your API documentation. It generates code that
+integrates seamlessly with your API endpoints, reducing development time and errors.
+
+[Learn more about the Create Client](../create-client/index.md)
+
+### JavaScript Libraries
+
+#### @api-platform/ld
+
+The [@api-platform/ld](https://www.npmjs.com/package/@api-platform/ld) JavaScript library simplifies working with Linked Data. It helps parse and serialize data in formats such as JSON-LD,
+making it easier to handle complex relationships in your applications.
+
+Example: Loading authors when required with a Linked Data approach:
+
+```json
+{
+    "@id": "/books/1",
+        "@type": ["https://schema.org/Book"],
+        "title": "Hyperion",
+        "author": "https://localhost/authors/1"
+}
+```
+
+Given an API referencing books and their authors, where `GET /books/1` returns:
+
+```javascript
+import ld from '@api-platform/ld'
+
+const pattern = new URLPattern("/authors/:id", "https://localhost");
+const books = await ld('/books', {
+    urlPattern: pattern,
+    onUpdate: (newBooks) => {
+        log()
+    }
+})
+
+function log() {
+    console.log(books.author?.name)
+}
+
+log()
+```
+
+With [@api-platform/ld](https://www.npmjs.com/package/@api-platform/ld), authors are automatically loaded when needed.
+
+[Read the full documentation](https://edge-side-api.rocks/linked-data).
+
+#### @api-platform/mercure
+
+[Mercure](https://mercure.rocks/spec) is a real-time communication protocol. The [@api-platform/mercure](https://www.npmjs.com/package/@api-platform/mercure)
+library enables you to subscribe to updates and deliver real-time data seamlessly.
+
+Example: Subscribing to author updates:
+
+```javascript
+import mercure, { close } from "@api-platform/mercure";
+
+const res = await mercure('https://localhost/authors/1', {
+    onUpdate: (author) => console.log(author)
+})
+
+const author = res.then(res => res.json())
+
+// Close if you need to 
+history.onpushstate = function(e) {
+    close('https://localhost/authors/1')
+}
+```
+
+Assuming `/authors/1` returned the following:
+
+```http request
+Link: <https://localhost/authors/1>; rel="self"
+Link: <https://localhost/.well-known/mercure>; rel="mercure"
+```
+
+An `EventSource` subscribes to the topic `https://localhost/authors/1` on the hub `https://localhost/.well-known/mercure`.
+
+[Read the full documentation](https://edge-side-api.rocks/mercure).
+
+#### @api-platform/api-doc-parser
+
+The [@api-platform/api-doc-parser](https://www.npmjs.com/package/@api-platform/api-doc-parser) library parses Hydra API documentation, making it easier to interact with APIs.
+It provides metadata handling and generates client code effortlessly.
+
+Key Features:
+
+- Parse Hydra API documentation.
+- Generate TypeScript-friendly models.
+- Support for filters, pagination, and more.
+
+Example: Parsing [Hydra](http://hydra-cg.com/) API Documentation:
+
+```javascript
+import { parseHydraDocumentation } from '@api-platform/api-doc-parser';
+
+parseHydraDocumentation('https://demo.api-platform.com').then(({api}) => console.log(api));
+```
+This example fetches Hydra documentation from `https://demo.api-platform.com`, parses it, and logs the resulting API
+structure. The `parseHydraDocumentation` method is particularly useful for building metadata-driven clients or handling advanced API interactions.
+
+[Read the full documentation](https://github.com/api-platform/api-doc-parser).
+
+
+