Merge 4.0

Author: soyuka

core/bootstrap.md

@@ -1,4 +1,4 @@
-# Bootstraping the core library
+# Bootstrapping the Core Library
 
 You may want to run a minimal version of API Platform. This one file runs API Platform (without GraphQL, Eloquent, Doctrine MongoDB...).
 It requires the following Composer packages:

core/client-integration.md

@@ -0,0 +1,143 @@
+# 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"
+}
+```
+
+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 frontend 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
+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).

core/content-negotiation.md

@@ -24,7 +24,7 @@ Available formats are:
 | [GraphQL](graphql.md)                                 | n/a         | n/a                           | yes                               |
 | [JSON:API](https://jsonapi.org/)                      | `jsonapi`   | `application/vnd.api+json`    | yes                               |
 | [HAL](https://stateless.group/hal_specification.html) | `jsonhal`   | `application/hal+json`        | yes                               |
-| [YAML](https://yaml.org/)                             | `yaml`      | `application/x-yaml`          | no                                |
+| [YAML](https://yaml.org/)                             | `yaml`      | `application/yaml`          | no                                |
 | [CSV](https://tools.ietf.org/html/rfc4180)            | `csv`       | `text/csv`                    | no                                |
 | [HTML](https://whatwg.org/) (API docs)                | `html`      | `text/html`                   | no                                |
 | [XML](https://www.w3.org/XML/)                        | `xml`       | `application/xml`, `text/xml` | no                                |

core/openapi.md

@@ -637,7 +637,7 @@ Manually register the Swagger UI controller:
 # app/config/routes.yaml
 api_doc:
   path: /api_documentation
-  controller: api_platform.swagger_ui.processor
+  controller: api_platform.action.documentation
 ```
 
 Change `/api_documentation` to the URI you wish Swagger UI to be accessible on.
@@ -649,9 +649,9 @@ Manually register the Swagger UI controller:
 ```php
 // routes/web.php
 use Illuminate\Support\Facades\Route;
-use ApiPlatform\Laravel\State\SwaggerUiProcessor;
+use ApiPlatform\Laravel\Controller\DocumentationController;
 
-Route::post('/api_documentation', SwaggerUiProcessor::class)
+Route::post('/api_documentation', DocumentationController::class)
     ->name('api_doc');
 ```
 

core/performance.md

@@ -45,7 +45,6 @@ The integration using the cache handler is quite simple. You just have to update
 +    --with github.com/dunglas/mercure/caddy \
 +    --with github.com/dunglas/vulcain/caddy \
 +    --with github.com/dunglas/caddy-cbrotli \
-+    --with github.com/caddyserver/cache-handler
 +    # You should use another storage than the default one (e.g. otter).
 +    # The list of the available storages can be find either on the documentation website (https://docs.souin.io/docs/storages/) or on the storages repository https://github.com/darkweak/storages
 +    --with github.com/caddyserver/cache-handler

create-client/typescript.md

@@ -1,6 +1,6 @@
 # TypeScript Interfaces
 
-The TypeScript Generator allows you to create [TypeScript interfaces](https://www.typescriptlang.org/docs/handbook/interfaces.html)
+The TypeScript Generator allows you to create [TypeScript interfaces](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#interfaces)
 that you can embed in any TypeScript-enabled project (React, Vue.js, Angular..).
 
 To do so, run the generator:

extra/contribution-guides.md

@@ -1,10 +1,14 @@
-# Contribution guides
+# Contribution Guides
 
-1. [API Platform Core Library](https://github.com/api-platform/core/blob/main/CONTRIBUTING.md)
-2. [API Platform Schema Generator](https://github.com/api-platform/schema-generator/blob/main/CONTRIBUTING.md)
-3. [API Platform Admin](https://github.com/api-platform/admin/blob/master/CONTRIBUTING.md)
-4. [API Platform CRUD Generator](https://github.com/api-platform/create-client/blob/master/CONTRIBUTING.md)
+## API Platform Core  
+- [General Contribution Guide](https://github.com/api-platform/core/blob/main/CONTRIBUTING.md)  
+- [Laravel-Specific Contribution Guide](https://github.com/api-platform/core/blob/main/src/Laravel/CONTRIBUTING.md)  
 
-**To report a security issue, please refer to [the dedicated document](security.md).**
+## API Platform Tools  
+- [Schema Generator Contribution Guide](https://github.com/api-platform/schema-generator/blob/main/CONTRIBUTING.md)  
+- [Admin Contribution Guide](https://github.com/api-platform/admin/blob/master/CONTRIBUTING.md)  
+- [CRUD Generator Contribution Guide](https://github.com/api-platform/create-client/blob/master/CONTRIBUTING.md)  
+
+**To report a security issue, please take a look at [the dedicated document](security.md).**
 
 <p align="center" class="symfonycasts"><a href="https://symfonycasts.com/screencast/contributing?cid=apip"><img src="../symfony/images/symfonycasts-player.png" alt="JWT screencast"><br>Watch the Contributing back to Symfony screencast (free)</a></p>

laravel/index.md

@@ -193,8 +193,7 @@ use ApiPlatform\Metadata\Get;
 #[Get(uriTemplate: '/my_custom_book/{id}')]
 class Book
 {
-    public string $id;
-    public string $title;
+    public function __construct(public string $id, public string $title) {}
 }
 ```
 
@@ -224,6 +223,7 @@ namespace App\State;
 use ApiPlatform\Metadata\Operation;
 use ApiPlatform\State\ProviderInterface;
 use App\Models\Book as BookModel;
+use App\ApiResource\Book;
 
 final class BookProvider implements ProviderInterface
 {
@@ -242,8 +242,8 @@ Register the state provider:
 
 namespace App\Providers;
 
-use ApiPlatform\State\ProviderInterface;
 use App\State\BookProvider;
+use ApiPlatform\State\ProviderInterface;
 use Illuminate\Contracts\Foundation\Application;
 use Illuminate\Support\ServiceProvider;
 
@@ -273,8 +273,7 @@ use App\State\BookProvider;
 #[Get(uriTemplate: '/my_custom_book/{id}', provider: BookProvider::class)]
 class Book
 {
-    public string $id;
-    public string $title;
+    public function __construct(public string $id, public string $title) {}
 }
 ```
 
@@ -626,6 +625,7 @@ API Platform provides an easy shortcut to some [useful filters](./filters.md), f
  namespace App\Models;
 
  use ApiPlatform\Metadata\ApiResource;
++use ApiPlatform\Metadata\QueryParameter;
 +use ApiPlatform\Laravel\Eloquent\Filter\PartialSearchFilter;
  use Illuminate\Database\Eloquent\Model;
 
@@ -645,6 +645,7 @@ It's also possible to enable filters on every exposed property:
  namespace App\Models;
 
  use ApiPlatform\Metadata\ApiResource;
++use ApiPlatform\Metadata\QueryParameter;
 +use ApiPlatform\Laravel\Eloquent\Filter\PartialSearchFilter;
 +use ApiPlatform\Laravel\Eloquent\Filter\OrderFilter;
  use Illuminate\Database\Eloquent\Model;

outline.yaml

@@ -70,6 +70,7 @@ chapters:
       - form-data
       - bootstrap
       - configuration
+      - client-integration
   - title: Schema Generator
     path: schema-generator
     items:

symfony/caddy.md

@@ -1,4 +1,4 @@
-# Configuring the Caddy Web Server
+# Configuring the Caddy Web Server with Symfony
 
 [The API Platform distribution](index.md) is shipped with [the Caddy web server](https://caddyserver.com).
 The build contains the [Mercure](../core/mercure.md) and the [Vulcain](https://vulcain.rocks) Caddy modules.