Skip to content

Commit 3382ff8

Browse files
alexandrebodinalexandrebodin
committed
Init Content API RFC
1 parent 8801c6b commit 3382ff8

File tree

1 file changed

+220
-0
lines changed

1 file changed

+220
-0
lines changed

‎rfcs/xxxx-v5-content-api.md‎

Lines changed: 220 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,220 @@
1+
- Start Date: 2023-09-05
2+
- RFC PR: (leave this empty)
3+
4+
# Summary
5+
6+
V5 is in preparation and will require making changes to the Content APIs (REST & GraphQL).
7+
8+
# Motivation
9+
10+
V5 Content Engine requires some breaking changes to the API, It is also the opportunity to simplify the API Response format following user feedbacks.
11+
12+
> The main goal of this RFC is to propose a simplified and v5 compatible format while offering a smoother migration path with a legacy format.
13+
14+
# Detailed design
15+
16+
### Endpoints
17+
18+
Based on the [Database changes planned](https://github.com/strapi/rfcs/pull/52),we will now mainly work with the `documentId` within the API.
19+
20+
**Collection Types**
21+
22+
| Method | Url | Desc |
23+
| -------- | ----------------------------------------------- | ----------------------------------------------------------------------- |
24+
| `GET` | `/api/:contentType`` | Find a list of documents |
25+
| `POST` | `/api/:contentType` | Create a document |
26+
| `GET` | `/api/:contentType/:documentId` | Find a document |
27+
| `PUT` | `/api/:contentType/:documentId` | Update a document |
28+
| `DELETE` | `/api/:contentType/:documentId` | Delete a document |
29+
| `POST` | `/api/:contentType/actions/:action` | Actions on the collection of documents (bulk actions, custom action...) |
30+
| `POST` | `/api/:contentType/:documentId/actions/:action` | Actions on a specific document |
31+
32+
**Single Types**
33+
34+
| Method | Url | Desc |
35+
| -------- | --------------------------------- | ------------------------------ |
36+
| `GET` | /api/:contentType | Find document |
37+
| `PUT` | /api/:contentType | Create or Update the document |
38+
| `DELETE` | /api/:contentType | Delete document |
39+
| `POST` | /api/:contentType/actions/:action | Actions on the single document |
40+
41+
### Add `documentId`
42+
43+
Introduction of the `documentId` field and renaming of the old `id` to `entryId` or `entityId`
44+
45+
**Example**
46+
47+
```tsx
48+
{
49+
"data": {
50+
"documentId": "clkgylmcc000008lcdd868feh",
51+
"entryId": "clkgylmcc000008lcdd868feh"
52+
},
53+
"meta": {
54+
"pagination": {
55+
"page": 1,
56+
"pageSize": 10
57+
}
58+
}
59+
}
60+
```
61+
62+
### Introduce a simplified format
63+
64+
We are planning to introduce a new version of the API response that flattens the structure and removes some of the complex nesting from v4.
65+
66+
To avoid conflicts between features & Content Type attributes we will keep the `meta` object but completely flatten the `attributes` & `data.attributes` sub paths.
67+
68+
**Before**
69+
70+
```json
71+
{
72+
"data": {
73+
"id": 1,
74+
"attributes": {
75+
"title": "Article A",
76+
"locale": "en",
77+
"createdAt": "2023-01-01T00:00:00.000Z",
78+
"updatedAt": "2023-01-01T00:00:00.000Z",
79+
"publishedAt": "2023-01-01T00:00:00.000Z",
80+
"relation": {
81+
"data": {
82+
"id": 1,
83+
"attributes": {
84+
"name": "Category A",
85+
"locale": "en",
86+
"createdAt": "2023-01-01T00:00:00.000Z",
87+
"updatedAt": "2023-01-01T00:00:00.000Z",
88+
"publishedAt": "2023-01-01T00:00:00.000Z"
89+
}
90+
}
91+
}
92+
}
93+
},
94+
"meta": {
95+
"pagination": {
96+
"page": 1,
97+
"pageSize": 10
98+
}
99+
}
100+
}
101+
```
102+
103+
**After**
104+
105+
```json
106+
{
107+
"data": {
108+
"documentId": "clkgylmcc000008lcdd868feh",
109+
"entryId": "cpmnyztbcc964008lcft812feo",
110+
"title": "Article A",
111+
"relation": {
112+
"documentId": "clkgylw7d000108lc4rw1bb6s",
113+
"entryId": 1,
114+
"name": "Category A",
115+
"meta": {
116+
"locale": "en",
117+
"createdAt": "2023-01-01T00:00:00.000Z",
118+
"updatedAt": "2023-01-01T00:00:00.000Z",
119+
"publishedAt": "2023-01-01T00:00:00.000Z"
120+
}
121+
},
122+
"meta": {
123+
"locale": "fr",
124+
"createdAt": "2023-01-01T00:00:00.000Z",
125+
"updatedAt": "2023-01-01T00:00:00.000Z",
126+
"publishedAt": "2023-01-01T00:00:00.000Z"
127+
}
128+
},
129+
"meta": {
130+
"pagination": {
131+
"page": 1,
132+
"pageSize": 10
133+
}
134+
}
135+
}
136+
```
137+
138+
### Separating meta attributes to avoid any current & future name conflicts
139+
140+
```json
141+
// Using a nested object
142+
{
143+
"data": {
144+
"documentId": "clkgylmcc000008lcdd868feh",
145+
"title": "Article A",
146+
"description": "My description",
147+
"meta": {
148+
"locale": "",
149+
"publishedAt": "",
150+
"createdAt": "",
151+
"createdBy": ""
152+
}
153+
}
154+
}
155+
```
156+
157+
Pros:
158+
159+
- No conflicts between user & system attributes
160+
- Clear separation in different objects
161+
- Easier extraction of all meta fields in one go
162+
163+
Cons
164+
165+
- Access is nested.
166+
- Lesser discoverability (need to know it’s in meta) ⇒ the _SDK and/or Typescript typings would make the discoverability issue irrelevant_
167+
168+
```tsx
169+
const locale = data.meta.locale;
170+
const { locale } = data.meta;
171+
172+
// better separation
173+
const { meta, ...attributes } = data;
174+
```
175+
176+
### Low level **relational support**
177+
178+
In order to keep the old relational system, we will return the `entryId` to allow managing low level relations.
179+
180+
```json
181+
{
182+
"data": {
183+
"id": "clkgylmcc000008lcdd868feh",
184+
"entryId": 1,
185+
"title": "..."
186+
}
187+
}
188+
```
189+
190+
# Release plan
191+
192+
Doing theses changes would break all the existing API Calls.
193+
194+
In order to reduce migration cost we are considering support a _deprecated_ response format:
195+
196+
- Keep the "id" name for the entry id
197+
- Support fetching the API with the old IDs
198+
- Keep the nested `data.attributes` format of v4
199+
200+
```tsx
201+
{
202+
"data": {
203+
"documentId": "clkgylmcc000008lcdd868feh"
204+
"id": "clkgylmcc000008lcdd868feh",
205+
"attributes": {
206+
// ...allAttributes
207+
},
208+
}
209+
}
210+
```
211+
212+
- This format could be configured to be the default one during migration.
213+
- We would support a query parameter to switch to the new format incrementally.
214+
215+
> The breaking changes are still forcing users to switch from calling the api with `id` to `documentId`
216+
217+
# Unresolved questions
218+
219+
- Should we use `id` or `documentId` in the new response format.
220+
- Should we use `entryId` or `entityId` to represent the underlying Ids to use for low level relations

0 commit comments

Comments
 (0)