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.

symfony/debugging.md

@@ -1,4 +1,4 @@
-# Debugging
+# Debugging with Symfony
 
 <p align="center" class="symfonycasts"><a href="https://symfonycasts.com/screencast/api-platform/profiler?cid=apip"><img src="images/symfonycasts-player.png" alt="API Platform debugging screencast"><br>Watch the Debugging API Platform screencast</a></p>
 

symfony/file-upload.md

@@ -67,7 +67,6 @@ use ApiPlatform\Metadata\Get;
 use ApiPlatform\Metadata\GetCollection;
 use ApiPlatform\Metadata\Post;
 use ApiPlatform\OpenApi\Model;
-use App\State\SaveMediaObject;
 use Doctrine\ORM\Mapping as ORM;
 use Symfony\Component\HttpFoundation\File\File;
 use Symfony\Component\Serializer\Annotation\Groups;

symfony/index.md

@@ -1,4 +1,4 @@
-# Getting Started With API Platform for Symfony
+# Getting Started With API Platform with Symfony
 
 ![The welcome page](images/api-platform-3.0-welcome.png)
 
@@ -460,7 +460,7 @@ bin/console make:entity --api-resource
 ```
 
 Doctrine's [attributes](https://www.doctrine-project.org/projects/doctrine-orm/en/current/reference/attributes-reference.html) map these entities to tables in the database.
-Mapping through [attributes](https://www.doctrine-project.org/projects/doctrine-orm/en/current/reference/attributes-reference.html) is also supported, if you prefer those.
+Mapping through [annotations](https://www.doctrine-project.org/projects/doctrine-annotations/en/current/index.html)  is still supported for backward compatibility, but they are considered deprecated and attributes are now the recommended approach.
 Both methods are convenient as they allow grouping the code and the configuration but, if you want to decouple classes from their metadata, you can switch to XML or YAML mappings.
 They are supported as well.