docs(client-integration): introduce documentation

core/client-integration.md

@@ -0,0 +1,145 @@
+# 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](https://marmelab.com/react-admin/).
+It automatically adapts to your API schema and provides extensive customization options. It can read an [OpenAPI](https://www.openapis.org/)
+specification or a [Hydra](https://www.hydra-cg.com/) specification. API Platform supports both [OpenAPI](openapi.md) and
+[Hydra](extending-jsonld-context.md#hydra) from scratch!
+
+[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://edge-side-api.rocks/linked-data) JavaScript library simplifies working with Linked Data.
+It helps parse and serialize data in formats such as [JSON-LD](extending-jsonld-context.md#json-ld), making it easier to
+handle complex relationships in your applications.
+
+For example, let's load authors when required with a Linked Data approach.
+Given an API referencing books and their authors, where `GET /books/1` returns:
+
+```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:
+
+Use an [URLPattern](https://urlpattern.spec.whatwg.org/) to load authors automatically when fetching an author property
+such as `books.author?.name`:
+
+```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://edge-side-api.rocks/linked-data), 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://edge-side-api.rocks/mercure)
+library enables you to subscribe to updates and deliver real-time data seamlessly.
+
+Our front-end library allows you to subscribe to updates with efficiency, re-using the hub connection and adding topics
+automatically as they get requested. API Platform [supports Mercure](mercure.md) and automatically sets the
+[Link header](https://mercure.rocks/spec#content-negotiation) making auto-discovery a breeze. For example:
+
+```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://github.com/api-platform/api-doc-parser)  that parses Hydra, Swagger,
+OpenAPI, and GraphQL documentation into an intermediate format for generating API clients and scaffolding code.
+It integrates well with API Platform and supports auto-detecting resource relationships.
+
+Key Features:
+
+- Multi-format support: Parses Hydra, Swagger (OpenAPI v2), OpenAPI v3, and GraphQL.
+- Intermediate representation: Converts API docs into a usable format for generating clients, scaffolding code, or building admin interfaces.
+- API Platform integration: Works seamlessly with API Platform.
+- Auto-detection of resource relationships: Automatically detects relationships between resources based on documentation.
+
+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).