API components showcase

This page demonstrates the API-specific components used across the Strapi documentation. For general-purpose components (admonitions, tabs, cards, badges…), see the components showcase.

Page summary:

This is a demo page for designers. It renders the Endpoint layout for both HTTP and JavaScript API calls, with parameters, request examples, and responses.

1. Endpoint (HTTP)

The Endpoint layout for an HTTP request, with parameters, a request example, and responses.

The parameters and the code examples display side by side in two columns only in the wide and max width view modes. In the default (centered) view mode, the layout collapses to a single column, with the parameters stacked above the code. Use the width toggle at the top of the page to switch between view modes and compare.

GET/api/:pluralApiId

Get documents

Returns a list of documents matching the query parameters.

Parameters

locale

String

optional

Locale to fetch documents for.

sort

String

optional

Sort the results.

pagination[page]

Integer

optional

Page number.

cURL

terminal

curl http://localhost:1337/api/restaurants?locale=en

JavaScript

const res = await fetch('http://localhost:1337/api/restaurants?locale=en');
const { data } = await res.json();

200

200 OK

{
  "data": [
    { "id": 1, "documentId": "abc123", "name": "Biscotte Restaurant" }
  ],
  "meta": { "pagination": { "page": 1, "pageCount": 1, "total": 1 } }
}

404

404 Not Found

{
  "data": null,
  "error": { "status": 404, "name": "NotFoundError", "message": "Not Found" }
}

2. Endpoint (JavaScript / Document Service API)

The kind="js" variant is for internal back-end APIs, such as the Document Service API, that are called from server code rather than over HTTP. For these, HTTP methods like GET or POST do not apply, so the endpoint shows the JavaScript method signature instead of a method pill and a URL path.

It follows the same two-column behavior: side by side in the wide and max width view modes, single column otherwise.

strapi.documents('api::article.article').findOne()

findOne()

Find a single document by its documentId.

Parameters

documentId

String

required

The documentId of the document.

populate

Object | String

optional

Relations, media, and components to populate.

const article = await strapi.documents('api::article.article').findOne({
  documentId: 'abc123',
  populate: '*',
});

200 OK

{ "documentId": "abc123", "title": "Hello world" }

3. Endpoint (GraphQL)

GraphQL is an HTTP API: every query and mutation is a POST request to the single /graphql endpoint. The request body carries the GraphQL query or mutation, so the Endpoint uses the HTTP layout with the GraphQL document shown in the request tabs.

POST/graphql

Query and mutate documents

Send a GraphQL query or mutation as the request body to the single /graphql endpoint.

Parameters

query

String

required

The GraphQL query or mutation document.

variables

Object

optional

Values for the variables used in the document.

Query

query Restaurants {
  restaurants {
    documentId
    name
  }
}

Mutation

mutation CreateRestaurant {
  createRestaurant(data: { name: "Biscotte Restaurant" }) {
    documentId
    name
  }
}

200 OK

{
  "data": {
    "restaurants": [
      { "documentId": "abc123", "name": "Biscotte Restaurant" }
    ]
  }
}