diff --git a/core/bootstrap.md b/core/bootstrap.md index 556a581deda..21bab4c747d 100644 --- a/core/bootstrap.md +++ b/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: diff --git a/core/client-integration.md b/core/client-integration.md new file mode 100644 index 00000000000..0d3ab5ad7c6 --- /dev/null +++ b/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: ; rel="self" +Link: ; 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). diff --git a/core/content-negotiation.md b/core/content-negotiation.md index bcbb9114e88..2622f39dfa5 100644 --- a/core/content-negotiation.md +++ b/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 | diff --git a/core/openapi.md b/core/openapi.md index 1f4d1833b6f..2a83ffff1a2 100644 --- a/core/openapi.md +++ b/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'); ``` diff --git a/core/performance.md b/core/performance.md index ac693840148..1d464561f80 100644 --- a/core/performance.md +++ b/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 diff --git a/create-client/typescript.md b/create-client/typescript.md index f974044db45..3771f2832c6 100644 --- a/create-client/typescript.md +++ b/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: diff --git a/extra/contribution-guides.md b/extra/contribution-guides.md index 3e3cd52aaa8..c9d6e33b947 100644 --- a/extra/contribution-guides.md +++ b/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).**

JWT screencast
Watch the Contributing back to Symfony screencast (free)

diff --git a/laravel/index.md b/laravel/index.md index bab1332e33c..6136b0c7c79 100644 --- a/laravel/index.md +++ b/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; diff --git a/outline.yaml b/outline.yaml index 2ab6b4879ea..0e50c8e99ae 100644 --- a/outline.yaml +++ b/outline.yaml @@ -70,6 +70,7 @@ chapters: - form-data - bootstrap - configuration + - client-integration - title: Schema Generator path: schema-generator items: diff --git a/symfony/caddy.md b/symfony/caddy.md index af0e3da931a..ce701f9cf90 100644 --- a/symfony/caddy.md +++ b/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. diff --git a/symfony/debugging.md b/symfony/debugging.md index e128a4dfce5..e69008eedf1 100644 --- a/symfony/debugging.md +++ b/symfony/debugging.md @@ -1,4 +1,4 @@ -# Debugging +# Debugging with Symfony

API Platform debugging screencast
Watch the Debugging API Platform screencast

diff --git a/symfony/file-upload.md b/symfony/file-upload.md index dc3b25458b4..9cc55907a51 100644 --- a/symfony/file-upload.md +++ b/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; diff --git a/symfony/index.md b/symfony/index.md index 0073627a427..04c69bfaad2 100644 --- a/symfony/index.md +++ b/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.