Skip to content

Commit 2f51922

Browse files
vinceAmstoutzvinceAmstoutz
committed
docs(client-integration): introduce documentation
1 parent 2fd0a82 commit 2f51922

File tree

2 files changed

+144
-0
lines changed

2 files changed

+144
-0
lines changed

‎core/client-integration.md

+143
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
# Client Integrations
2+
3+
## Edge Side API (ESA)
4+
5+
> [Edge Side APIs (ESA)](https://edge-side-api.rocks/) is an architectural pattern that allows the creation of more
6+
> reliable, efficient, and less resource-intensive APIs. It revives the core REST/HATEOAS principles while taking full
7+
> advantage of the new capabilities provided by the web platform.
8+
>
9+
> ESA promotes a mixed approach (synchronous and asynchronous), offering simplicity in development and use, exceptional
10+
> performance, and the ability for clients to receive real-time updates of the resources they fetched. ESA also leverages
11+
> existing standards to expose API documentation, enabling the creation of generic clients capable of discovering the
12+
> API’s capabilities at runtime.
13+
>
14+
> — *From [ESA White Paper](https://edge-side-api.rocks/white-paper)*
15+
16+
## JavaScript Client Integrations
17+
18+
API Platform offers a suite of tools and libraries that streamline the integration of JavaScript clients with APIs.
19+
These tools simplify development by automating tasks such as data fetching, administration panel creation,
20+
and real-time updates. Below is a detailed overview of the available clients, libraries, and their usage.
21+
22+
### Clients and Tools Overview
23+
24+
#### Admin
25+
26+
API Platform Admin is a dynamic administration panel generator built with [React-Admin](https://marmelab.com/react-admin/).
27+
It automatically adapts to your API schema and provides extensive customization options. It can read an [OpenAPI](https://www.openapis.org/)
28+
specification or a [Hydra](https://www.hydra-cg.com/) specification. API Platform supports both [OpenAPI](openapi.md) and
29+
[Hydra](extending-jsonld-context.md#hydra) from scratch!
30+
31+
[Learn more about API Platform Admin](../admin/index.md).
32+
33+
#### Create Client
34+
35+
The Client Generator creates JavaScript/TypeScript clients based on your API documentation. It generates code that
36+
integrates seamlessly with your API endpoints, reducing development time and errors.
37+
38+
[Learn more about the Create Client](../create-client/index.md)
39+
40+
### JavaScript Libraries
41+
42+
#### api-platform/ld
43+
44+
The [api-platform/ld](https://edge-side-api.rocks/linked-data) JavaScript library simplifies working with Linked Data.
45+
It helps parse and serialize data in formats such as [JSON-LD](extending-jsonld-context.md#json-ld), making it easier to
46+
handle complex relationships in your applications.
47+
48+
For example, let's load authors when required with a Linked Data approach.
49+
Given an API referencing books and their authors, where `GET /books/1` returns:
50+
51+
```json
52+
{
53+
"@id": "/books/1",
54+
"@type": ["https://schema.org/Book"],
55+
"title": "Hyperion",
56+
"author": "https://localhost/authors/1"
57+
}
58+
```
59+
60+
Use an [URLPattern](https://urlpattern.spec.whatwg.org/) to load authors automatically when fetching an author property
61+
such as `books.author?.name`:
62+
63+
```javascript
64+
import ld from '@api-platform/ld'
65+
66+
const pattern = new URLPattern("/authors/:id", "https://localhost");
67+
const books = await ld('/books', {
68+
urlPattern: pattern,
69+
onUpdate: (newBooks) => {
70+
log()
71+
}
72+
})
73+
74+
function log() {
75+
console.log(books.author?.name)
76+
}
77+
78+
log()
79+
```
80+
81+
With [api-platform/ld](https://edge-side-api.rocks/linked-data), authors are automatically loaded when needed.
82+
83+
[Read the full documentation](https://edge-side-api.rocks/linked-data).
84+
85+
#### api-platform/mercure
86+
87+
[Mercure](https://mercure.rocks/spec) is a real-time communication protocol. The [api-platform/mercure](https://edge-side-api.rocks/mercure)
88+
library enables you to subscribe to updates and deliver real-time data seamlessly.
89+
90+
Our frontend library allows you to subscribe to updates with efficiency, re-using the hub connection and adding topics
91+
automatically as they get requested. API Platform [supports Mercure](mercure.md) and automatically sets the
92+
[Link header](https://mercure.rocks/spec#content-negotiation) making auto-discovery a breeze. For example:
93+
94+
```javascript
95+
import mercure, { close } from "@api-platform/mercure";
96+
97+
const res = await mercure('https://localhost/authors/1', {
98+
onUpdate: (author) => console.log(author)
99+
})
100+
101+
const author = res.then(res => res.json())
102+
103+
// Close if you need to
104+
history.onpushstate = function(e) {
105+
close('https://localhost/authors/1')
106+
}
107+
```
108+
109+
Assuming `/authors/1` returned the following:
110+
111+
```http request
112+
Link: <https://localhost/authors/1>; rel="self"
113+
Link: <https://localhost/.well-known/mercure>; rel="mercure"
114+
```
115+
116+
An `EventSource` subscribes to the topic `https://localhost/authors/1` on the hub `https://localhost/.well-known/mercure`.
117+
118+
[Read the full documentation](https://edge-side-api.rocks/mercure).
119+
120+
#### api-platform/api-doc-parser
121+
122+
The [api-platform/api-doc-parser](https://github.com/api-platform/api-doc-parser) that parses Hydra, Swagger,
123+
OpenAPI, and GraphQL documentation into an intermediate format for generating API clients and scaffolding code.
124+
It integrates well with API Platform and supports auto-detecting resource relationships.
125+
126+
Key Features:
127+
128+
- Multi-format support: Parses Hydra, Swagger (OpenAPI v2), OpenAPI v3, and GraphQL.
129+
- Intermediate representation: Converts API docs into a usable format for generating clients, scaffolding code, or building admin interfaces.
130+
- API Platform integration: Works seamlessly with API Platform.
131+
- Auto-detection of resource relationships: Automatically detects relationships between resources based on documentation.
132+
133+
Example: Parsing [Hydra](http://hydra-cg.com/) API Documentation:
134+
135+
```javascript
136+
import { parseHydraDocumentation } from '@api-platform/api-doc-parser';
137+
138+
parseHydraDocumentation('https://demo.api-platform.com').then(({api}) => console.log(api));
139+
```
140+
This example fetches Hydra documentation from `https://demo.api-platform.com`, parses it, and logs the resulting API
141+
structure. The `parseHydraDocumentation` method is particularly useful for building metadata-driven clients or handling advanced API interactions.
142+
143+
[Read the full documentation](https://github.com/api-platform/api-doc-parser).

‎outline.yaml

+1
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,7 @@ chapters:
7070
- form-data
7171
- bootstrap
7272
- configuration
73+
- client-integration
7374
- title: Schema Generator
7475
path: schema-generator
7576
items:

0 commit comments

Comments
 (0)