Skip to content

Commit 30bb08d

Browse files
pwizlaudimberto
pwizla
and
udimberto
authored
New API layout (#1756)
* Update code styles when inside a table (#1745) * Add 'SideBySide' components to apply the REST API layout splitted (#1734) * Update 'SideBySideContainer' component to display the right-side nav when it fits (#1757) * internal: API Request component for language switch (#1774) * internal: Annotation component (#1792) * Introduce REST API-specific sidebar * Adjust REST API introduction content * Adjust REST API parameters content * Adjust Sort & Pagination content * Adjust Filters, Locale, and Publication State content * Replace displayed sidebar in interactive query builder page * Adjust Populate and Select content * Adjust Relations content --------- Co-authored-by: Udi Silvestre <[email protected]>
1 parent 2e7df8c commit 30bb08d

27 files changed

+1408
-74
lines changed

Diff for: ‎docusaurus/docs/dev-docs/api/rest.md

+64-8
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
---
2-
title: REST API
2+
title: REST API
33
description: Interact with your Content-Types using the REST API endpoints Strapi generates for you.
4+
displayed_sidebar: restApiSidebar
45

56
---
67

@@ -104,10 +105,18 @@ Requests return a response as an object which usually includes the following key
104105
Some plugins (including Users & Permissions and Upload) may not follow this response format.
105106
:::
106107

108+
<SideBySideContainer>
109+
110+
<SideBySideColumn>
111+
107112
### Get entries
108113

109114
Returns entries matching the query filters (see [API parameters](/dev-docs/api/rest/parameters) documentation).
110115

116+
</SideBySideColumn>
117+
118+
<SideBySideColumn>
119+
111120
<ApiCall>
112121

113122
<Request>
@@ -151,11 +160,22 @@ Returns entries matching the query filters (see [API parameters](/dev-docs/api/r
151160

152161
</ApiCall>
153162

163+
</SideBySideColumn>
164+
165+
</SideBySideContainer>
166+
167+
<SideBySideContainer>
168+
169+
<SideBySideColumn>
154170

155171
### Get an entry
156172

157173
Returns an entry by `id`.
158174

175+
</SideBySideColumn>
176+
177+
<SideBySideColumn>
178+
159179
<ApiCall>
160180

161181
<Request title="Example request">
@@ -187,12 +207,28 @@ Returns an entry by `id`.
187207

188208
</ApiCall>
189209

210+
</SideBySideColumn>
211+
212+
</SideBySideContainer>
213+
214+
<SideBySideContainer>
215+
216+
<SideBySideColumn>
217+
190218
### Create an entry
191219

192220
Creates an entry and returns its value.
193221

194222
If the [Internationalization (i18n) plugin](/dev-docs/plugins/i18n.md) is installed, it's possible to use POST requests to the REST API to [create localized entries](/dev-docs/plugins/i18n.md#creating-a-new-localized-entry).
195223

224+
:::note
225+
While creating an entry, you can define its relations and their order (see [Managing relations through the REST API](/dev-docs/api/rest/relations.md) for more details).
226+
:::
227+
228+
</SideBySideColumn>
229+
230+
<SideBySideColumn>
231+
196232
<ApiCall>
197233

198234
<Request title="Example request">
@@ -232,16 +268,29 @@ If the [Internationalization (i18n) plugin](/dev-docs/plugins/i18n.md) is instal
232268

233269
</ApiCall>
234270

235-
:::note
236-
While creating an entry, you can define its relations and their order (see [Managing relations through the REST API](/dev-docs/api/rest/relations.md) for more details).
237-
:::
271+
</SideBySideColumn>
272+
</SideBySideContainer>
273+
274+
275+
<SideBySideContainer>
276+
277+
<SideBySideColumn>
238278

239279
### Update an entry
240280

241281
Partially updates an entry by `id` and returns its value.
242282

243283
Fields that aren't sent in the query are not changed in the database. Send a `null` value to clear fields.
244284

285+
:::note NOTES
286+
* Even with the [Internationalization (i18n) plugin](/dev-docs/plugins/i18n) installed, it's currently not possible to [update the locale of an entry](/dev-docs/plugins/i18n#updating-an-entry).
287+
* While updating an entry, you can define its relations and their order (see [Managing relations through the REST API](/dev-docs/api/rest/relations.md) for more details).
288+
:::
289+
290+
</SideBySideColumn>
291+
292+
<SideBySideColumn>
293+
245294
<ApiCall>
246295

247296
<Request title="Example request">
@@ -277,15 +326,19 @@ Fields that aren't sent in the query are not changed in the database. Send a `nu
277326

278327
</ApiCall>
279328

280-
:::note NOTES
281-
* Even with the [Internationalization (i18n) plugin](/dev-docs/plugins/i18n) installed, it's currently not possible to [update the locale of an entry](/dev-docs/plugins/i18n#updating-an-entry).
282-
* While updating an entry, you can define its relations and their order (see [Managing relations through the REST API](/dev-docs/api/rest/relations.md) for more details).
283-
:::
329+
</SideBySideColumn>
330+
</SideBySideContainer >
331+
332+
<SideBySideContainer>
333+
334+
<SideBySideColumn>
284335

285336
### Delete an entry
286337

287338
Deletes an entry by `id` and returns its value.
339+
</SideBySideColumn>
288340

341+
<SideBySideColumn>
289342
<ApiCall>
290343

291344
<Request title="Example request">
@@ -310,3 +363,6 @@ Deletes an entry by `id` and returns its value.
310363
</Response>
311364

312365
</ApiCall>
366+
367+
</SideBySideColumn>
368+
</SideBySideContainer>

Diff for: ‎docusaurus/docs/dev-docs/api/rest/filters-locale-publication.md

+87-17
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: Filters, Locale, and Publication State
33
description: Use Strapi's REST API to filter the results of your requests.
44
sidebarDepth: 3
5-
5+
displayed_sidebar: restApiSidebar
66
---
77

88
import QsIntroFull from '/docs/snippets/qs-intro-full.md'
@@ -55,6 +55,23 @@ The following operators are available:
5555
| `$and` | Joins the filters in an "and" expression |
5656
| `$not` | Joins the filters in an "not" expression |
5757

58+
:::caution
59+
By default, the filters can only be used from `find` endpoints generated by the Content-type Builder and the CLI.
60+
:::
61+
62+
<SideBySideContainer>
63+
<SideBySideColumn>
64+
65+
### Example: Find users having 'John' as a first name
66+
67+
You can use the `$eq` filter operator to find an exact match.
68+
69+
</SideBySideColumn>
70+
71+
<SideBySideColumn>
72+
73+
<br />
74+
5875
<ApiCall>
5976
<Request title="Find users having 'John' as first name">
6077

@@ -104,6 +121,22 @@ await request(`/api/users?${query}`);
104121

105122
</details>
106123

124+
</SideBySideColumn>
125+
</SideBySideContainer>
126+
127+
<SideBySideContainer>
128+
<SideBySideColumn>
129+
130+
### Example: Find multiple restaurants with ids 3, 6,8
131+
132+
You can use the `$in` filter operator with an array of values to find multiple exact values.
133+
134+
</SideBySideColumn>
135+
136+
<SideBySideColumn>
137+
138+
<br />
139+
107140
<ApiCall>
108141
<Request title="Find multiple restaurants with ids 3, 6, 8">
109142

@@ -169,14 +202,21 @@ await request(`/api/restaurants?${query}`);
169202

170203
</details>
171204

172-
:::caution
173-
By default, the filters can only be used from `find` endpoints generated by the Content-type Builder and the CLI.
174-
:::
205+
</SideBySideColumn>
206+
</SideBySideContainer>
207+
208+
<SideBySideContainer>
209+
<SideBySideColumn>
175210

176211
### Complex filtering
177212

178213
Complex filtering is combining multiple filters using advanced methods such as combining `$and` & `$or`. This allows for more flexibility to request exactly the data needed.
179214

215+
</SideBySideColumn>
216+
217+
<SideBySideColumn>
218+
219+
<br />
180220
<ApiCall>
181221
<Request title="Find books with 2 possible dates and a specific author">
182222

@@ -251,10 +291,38 @@ await request(`/api/books?${query}`);
251291

252292
</details>
253293

294+
</SideBySideColumn>
295+
</SideBySideContainer>
296+
297+
<SideBySideContainer>
298+
<SideBySideColumn>
299+
254300
### Deep filtering
255301

256302
Deep filtering is filtering on a relation's fields.
257303

304+
<br />
305+
306+
:::caution
307+
308+
- Querying your API with deep filters may cause performance issues. If one of your deep filtering queries is too slow, we recommend building a custom route with an optimized version of the query.
309+
- Deep filtering isn't available for polymorphic relations (eg: Dynamic Zones & Media Fields).
310+
311+
:::
312+
313+
:::note
314+
315+
- Relations, media fields, components, and dynamic zones are not populated by default. Use the `populate` parameter to populate these data structures (see [`populate` documentation](/dev-docs/api/rest/populate-select#population))
316+
- It is not possible to filter on dynamic zones or media fields.
317+
318+
:::
319+
320+
</SideBySideColumn>
321+
322+
<SideBySideColumn>
323+
324+
<br />
325+
258326
<ApiCall>
259327
<Request title="Find restaurants owned by a chef who belongs to a 5-star restaurant">
260328

@@ -319,19 +387,9 @@ await request(`/api/restaurants?${query}`);
319387

320388
</details>
321389

322-
:::caution
323-
324-
- Querying your API with deep filters may cause performance issues. If one of your deep filtering queries is too slow, we recommend building a custom route with an optimized version of the query.
325-
- Deep filtering isn't available for polymorphic relations (eg: Dynamic Zones & Media Fields).
326-
327-
:::
328-
329-
:::note
330-
331-
- Relations, media fields, components, and dynamic zones are not populated by default. Use the `populate` parameter to populate these data structures (see [population documentation](/dev-docs/api/rest/populate-select#population))
332-
- It is not possible to filter on dynamic zones or media fields
390+
</SideBySideColumn>
391+
</SideBySideContainer>
333392

334-
:::
335393

336394
## Locale
337395

@@ -341,7 +399,10 @@ await request(`/api/restaurants?${query}`);
341399
- [Localization should be enabled for the content-type](/user-docs/content-type-builder/creating-new-content-type.md#creating-a-new-content-type).
342400
:::
343401

344-
The `locale` API parameter can be used to [get entries from a specific locale](/dev-docs/plugins/i18n.md#getting-localized-entries-with-the-locale-parameter).
402+
The `locale` API parameter can be used to get entries from a specific locale (see [i18n plugin documentation](/dev-docs/plugins/i18n.md#getting-localized-entries-with-the-locale-parameter)).
403+
404+
<SideBySideContainer>
405+
<SideBySideColumn>
345406

346407
## Publication State
347408

@@ -354,6 +415,12 @@ Queries can accept a `publicationState` parameter to fetch entries based on thei
354415
- `live`: returns only published entries (default)
355416
- `preview`: returns both draft entries & published entries
356417

418+
</SideBySideColumn>
419+
420+
<SideBySideColumn>
421+
422+
<br /><br />
423+
357424
<ApiCall>
358425
<Request title="Get both published and draft articles">
359426

@@ -409,6 +476,9 @@ await request(`/api/articles?${query}`);
409476

410477
</details>
411478

479+
</SideBySideColumn>
480+
</SideBySideContainer>
481+
412482
:::tip
413483
To retrieve only draft entries, combine the `preview` publication state and the `publishedAt` fields:
414484

Diff for: ‎docusaurus/docs/dev-docs/api/rest/interactive-query-builder.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: Interactive Query Builder
33
description: Use an interactive tool that leverages the querystring library to build your query URL
4-
displayed_sidebar: devDocsSidebar
4+
displayed_sidebar: restApiSidebar
55
---
66

77
# Build your query URL with Strapi's interactive tool

Diff for: ‎docusaurus/docs/dev-docs/api/rest/parameters.md

+5-5
Original file line numberDiff line numberDiff line change
@@ -15,15 +15,15 @@ The following API parameters are available:
1515

1616
| Operator | Type | Description |
1717
| ------------------ | ------------- | ----------------------------------------------------- |
18-
| `sort` | String or Array | [Sort the response](/dev-docs/api/rest/sort-pagination.md#sorting) |
19-
| `filters` | Object | [Filter the response](/dev-docs/api/rest/filters-locale-publication#filtering) |
2018
| `populate` | String or Object | [Populate relations, components, or dynamic zones](/dev-docs/api/rest/populate-select#population) |
2119
| `fields` | Array | [Select only specific fields to display](/dev-docs/api/rest/populate-select#field-selection) |
22-
| `pagination` | Object | [Page through entries](/dev-docs/api/rest/sort-pagination.md#pagination) |
23-
| `publicationState` | String | [Select the Draft & Publish state](/dev-docs/api/rest/filters-locale-publication#publication-state)<br/><br/>Only accepts the following values:<ul><li>`live`(default)</li><li>`preview`</li></ul> |
20+
| `filters` | Object | [Filter the response](/dev-docs/api/rest/filters-locale-publication#filtering) |
2421
| `locale` | String or Array | [Select one or multiple locales](/dev-docs/api/rest/filters-locale-publication#locale) |
22+
| `publicationState` | String | [Select the Draft & Publish state](/dev-docs/api/rest/filters-locale-publication#publication-state)<br/><br/>Only accepts the following values:<ul><li>`live`(default)</li><li>`preview`</li></ul> |
23+
| `sort` | String or Array | [Sort the response](/dev-docs/api/rest/sort-pagination.md#sorting) |
24+
| `pagination` | Object | [Page through entries](/dev-docs/api/rest/sort-pagination.md#pagination) |
2525

26-
Query parameters use the LHS bracket syntax (i.e. they are encoded using square brackets `[]`)
26+
Query parameters use the [LHS bracket syntax](https://christiangiacomi.com/posts/rest-design-principles/#lhs-brackets) (i.e. they are encoded using square brackets `[]`).
2727

2828
:::tip
2929
A wide range of REST API parameters can be used and combined to query your content, which can result in long and complex query URLs.<br/>👉 You can use Strapi's [interactive query builder](/dev-docs/api/rest/interactive-query-builder) tool to build query URLs more conveniently. 🤗

0 commit comments

Comments
 (0)