Skip to content

Commit

Permalink
New API layout (#1756)
Browse files Browse the repository at this point in the history 
* 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]>
  • Loading branch information
@pwizla @udimberto
pwizla and udimberto authored Jul 19, 2023
1 parent 2e7df8c commit 30bb08d
Show file tree
Hide file tree
Showing 27 changed files with 1,408 additions and 74 deletions.
72 changes: 64 additions & 8 deletions docusaurus/docs/dev-docs/api/rest.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
---
title: REST API
title: REST API
description: Interact with your Content-Types using the REST API endpoints Strapi generates for you.
displayed_sidebar: restApiSidebar

---

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

<SideBySideContainer>

<SideBySideColumn>

### Get entries

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

</SideBySideColumn>

<SideBySideColumn>

<ApiCall>

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

</ApiCall>

</SideBySideColumn>

</SideBySideContainer>

<SideBySideContainer>

<SideBySideColumn>

### Get an entry

Returns an entry by `id`.

</SideBySideColumn>

<SideBySideColumn>

<ApiCall>

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

</ApiCall>

</SideBySideColumn>

</SideBySideContainer>

<SideBySideContainer>

<SideBySideColumn>

### Create an entry

Creates an entry and returns its value.

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).

:::note
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).
:::

</SideBySideColumn>

<SideBySideColumn>

<ApiCall>

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

</ApiCall>

:::note
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).
:::
</SideBySideColumn>
</SideBySideContainer>


<SideBySideContainer>

<SideBySideColumn>

### Update an entry

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

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

:::note NOTES
* 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).
* 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).
:::

</SideBySideColumn>

<SideBySideColumn>

<ApiCall>

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

</ApiCall>

:::note NOTES
* 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).
* 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).
:::
</SideBySideColumn>
</SideBySideContainer >

<SideBySideContainer>

<SideBySideColumn>

### Delete an entry

Deletes an entry by `id` and returns its value.
</SideBySideColumn>

<SideBySideColumn>
<ApiCall>

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

</ApiCall>

</SideBySideColumn>
</SideBySideContainer>
104 changes: 87 additions & 17 deletions docusaurus/docs/dev-docs/api/rest/filters-locale-publication.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
title: Filters, Locale, and Publication State
description: Use Strapi's REST API to filter the results of your requests.
sidebarDepth: 3

displayed_sidebar: restApiSidebar
---

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

:::caution
By default, the filters can only be used from `find` endpoints generated by the Content-type Builder and the CLI.
:::

<SideBySideContainer>
<SideBySideColumn>

### Example: Find users having 'John' as a first name

You can use the `$eq` filter operator to find an exact match.

</SideBySideColumn>

<SideBySideColumn>

<br />

<ApiCall>
<Request title="Find users having 'John' as first name">

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

</details>

</SideBySideColumn>
</SideBySideContainer>

<SideBySideContainer>
<SideBySideColumn>

### Example: Find multiple restaurants with ids 3, 6,8

You can use the `$in` filter operator with an array of values to find multiple exact values.

</SideBySideColumn>

<SideBySideColumn>

<br />

<ApiCall>
<Request title="Find multiple restaurants with ids 3, 6, 8">

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

</details>

:::caution
By default, the filters can only be used from `find` endpoints generated by the Content-type Builder and the CLI.
:::
</SideBySideColumn>
</SideBySideContainer>

<SideBySideContainer>
<SideBySideColumn>

### Complex filtering

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.

</SideBySideColumn>

<SideBySideColumn>

<br />
<ApiCall>
<Request title="Find books with 2 possible dates and a specific author">

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

</details>

</SideBySideColumn>
</SideBySideContainer>

<SideBySideContainer>
<SideBySideColumn>

### Deep filtering

Deep filtering is filtering on a relation's fields.

<br />

:::caution

- 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.
- Deep filtering isn't available for polymorphic relations (eg: Dynamic Zones & Media Fields).

:::

:::note

- 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))
- It is not possible to filter on dynamic zones or media fields.

:::

</SideBySideColumn>

<SideBySideColumn>

<br />

<ApiCall>
<Request title="Find restaurants owned by a chef who belongs to a 5-star restaurant">

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

</details>

:::caution

- 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.
- Deep filtering isn't available for polymorphic relations (eg: Dynamic Zones & Media Fields).

:::

:::note

- 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))
- It is not possible to filter on dynamic zones or media fields
</SideBySideColumn>
</SideBySideContainer>

:::

## Locale

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

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).
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)).

<SideBySideContainer>
<SideBySideColumn>

## Publication State

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

</SideBySideColumn>

<SideBySideColumn>

<br /><br />

<ApiCall>
<Request title="Get both published and draft articles">

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

</details>

</SideBySideColumn>
</SideBySideContainer>

:::tip
To retrieve only draft entries, combine the `preview` publication state and the `publishedAt` fields:

Expand Down
2 changes: 1 addition & 1 deletion docusaurus/docs/dev-docs/api/rest/interactive-query-builder.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: Interactive Query Builder
description: Use an interactive tool that leverages the querystring library to build your query URL
displayed_sidebar: devDocsSidebar
displayed_sidebar: restApiSidebar
---

# Build your query URL with Strapi's interactive tool
Expand Down
10 changes: 5 additions & 5 deletions docusaurus/docs/dev-docs/api/rest/parameters.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,15 +15,15 @@ The following API parameters are available:

| Operator | Type | Description |
| ------------------ | ------------- | ----------------------------------------------------- |
| `sort` | String or Array | [Sort the response](/dev-docs/api/rest/sort-pagination.md#sorting) |
| `filters` | Object | [Filter the response](/dev-docs/api/rest/filters-locale-publication#filtering) |
| `populate` | String or Object | [Populate relations, components, or dynamic zones](/dev-docs/api/rest/populate-select#population) |
| `fields` | Array | [Select only specific fields to display](/dev-docs/api/rest/populate-select#field-selection) |
| `pagination` | Object | [Page through entries](/dev-docs/api/rest/sort-pagination.md#pagination) |
| `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> |
| `filters` | Object | [Filter the response](/dev-docs/api/rest/filters-locale-publication#filtering) |
| `locale` | String or Array | [Select one or multiple locales](/dev-docs/api/rest/filters-locale-publication#locale) |
| `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> |
| `sort` | String or Array | [Sort the response](/dev-docs/api/rest/sort-pagination.md#sorting) |
| `pagination` | Object | [Page through entries](/dev-docs/api/rest/sort-pagination.md#pagination) |

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

:::tip
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. 🤗
Expand Down
Loading

1 comment on commit 30bb08d

@vercel
Copy link

@vercel vercel bot commented on 30bb08d Jul 19, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Successfully deployed to the following URLs:

documentation – ./

documentation-strapijs.vercel.app
docs-vercel-v4.strapi.io
documentation-git-main-strapijs.vercel.app

Please sign in to comment.