Skip to content

Commit 16a3ea3

Browse files
alexandrebodinalexandrebodin
committed
Init Content API RFC
1 parent 8801c6b commit 16a3ea3

File tree

1 file changed

+217
-0
lines changed

1 file changed

+217
-0
lines changed

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

Lines changed: 217 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,217 @@
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+
{
142+
"data": {
143+
"documentId": "clkgylmcc000008lcdd868feh",
144+
"title": "Article A",
145+
"description": "My description",
146+
"meta": {
147+
"locale": "",
148+
"publishedAt": "",
149+
"createdAt": "",
150+
"createdBy": ""
151+
}
152+
}
153+
}
154+
```
155+
156+
Pros:
157+
158+
- No conflicts between user & system attributes
159+
- Clear separation in different objects
160+
- Easier extraction of all meta fields in one go
161+
162+
Cons
163+
164+
- Access is nested.
165+
- Lesser discoverability (need to know it’s in meta) ⇒ the _SDK and/or Typescript typings would make the discoverability issue irrelevant_
166+
167+
```tsx
168+
const locale = data.meta.locale;
169+
const { locale } = data.meta;
170+
171+
// better separation
172+
const { meta, ...attributes } = data;
173+
```
174+
175+
### Low level **relational support**
176+
177+
In order to keep the old relational system, we will return the `entryId` to allow managing low level relations.
178+
179+
```json
180+
{
181+
"data": {
182+
"id": "clkgylmcc000008lcdd868feh",
183+
"entryId": 1,
184+
"title": "..."
185+
}
186+
}
187+
```
188+
189+
# Release plan
190+
191+
Doing theses changes would break all the existing API Calls.
192+
193+
In order to reduce migration cost we are considering support a _deprecated_ response format:
194+
195+
- Keep the "id" name for the entry id
196+
- Support fetching the API with the old IDs
197+
- Keep the nested `data.attributes` format of v4
198+
199+
```tsx
200+
{
201+
"data": {
202+
"documentId": "clkgylmcc000008lcdd868feh"
203+
"id": "clkgylmcc000008lcdd868feh",
204+
"attributes": {},
205+
}
206+
}
207+
```
208+
209+
- This format could be configured to be the default one during migration.
210+
- We would support a query parameter to switch to the new format incrementally.
211+
212+
> The breaking changes are still forcing users to switch from calling the api with `id` to `documentId`
213+
214+
# Unresolved questions
215+
216+
- Should we use `id` or `documentId` in the new response format.
217+
- Should we use `entryId` or `entityId` to represent the underlying Ids to use for low level relations

0 commit comments

Comments
 (0)