# REST API

The REST API allows accessing the content-types through API endpoints that Strapi automatically creates.

API parameters can be used to filter, sort, and paginate results and to select fields and relations to populate). Additionally, specific parameters related to optional Strapi features can be used, like publication state and locale.

# API Parameters

Query parameters use the LHS bracket syntax (i.e. they are encoded using square brackets []).

The following parameters are available:

Operator Type Description
sort String/Array Sorting the response
filters Object Filter the response
populate String/Object Populate relations, components, or dynamic zones
fields Array Select only specific fields to display
pagination Object Page through entries
publicationState String Select the draft & publish state

Only accepts the following values:
  • live
  • preview
locale String/Array Select one ore multiple locales

💡 TIP

Strapi takes advantage of the ability of qs (opens new window) to parse nested objects to create more complex queries. Use qs directly to generate complex queries instead of creating them manually.

Example using qs 
const qs = require('qs');
const query = qs.stringify({
  sort: ['title:asc'],
  filters: {
    title: {
      $eq: 'hello',
    },
  },
  populate: '*',
  fields: ['title'],
  pagination: {
    pageSize: 10,
    page: 1,
  },
  publicationState: 'live',
  locale: ['en'],
}, {
  encodeValuesOnly: true, // prettify url
});

await request(`/api/books?${query}`);
// GET /api/books?sort[0]=title%3Aasc&filters[title][$eq]=hello&populate=%2A&fields[0]=title&pagination[pageSize]=10&pagination[page]=1&publicationState=live&locale[0]=en

# API Endpoints

Creating a content-type automatically creates some REST API endpoints available to interact with it.

✏️ NOTE

Components don't have API endpoints.

# Endpoints

For each Content-Type, the following endpoints are automatically generated:

Examples

# Unified response format

Whatever the query, the response is always an object with the following keys:

  • data: the response data itself, which could be:

    • a single entry, as an object with the following keys:
      • id (number)
      • attributes (object)
      • meta (object)
    • a list of entries, as an array of objects
    • a custom response

  • meta(object): information about pagination, publication state, available locales, etc.

  • error (object, optional): information about any error thrown by the request

# Get entries

Returns entries matching the query filters (see parameters documentation).

Example request

GET http://localhost:1337/api/restaurants

Example response

{
  "data": [
    {
      "id": 1,
      "attributes": {
        "title": "Restaurant A",
        "description": "Restaurant A's description"
      },
      "meta": {
        "availableLocales": []
      }
    },
    {
      "id": 2,
      "attributes": {
        "title": "Restaurant B",
        "description": "Restaurant B's description"
      },
      "meta": {
        "availableLocales": []
      }
    },
  ],
  "meta": {}
}

# Get an entry

Returns an entry by id.

Example request

GET http://localhost:1337/api/restaurants/1

Example response

{
  "data": {
    "id": 1,
    "attributes": {
      "title": "Restaurant A",
      "description": "Restaurant A's description"
    },
    "meta": {
      "availableLocales": []
    }
  },
  "meta": {}
}

# Create an entry

Creates an entry and returns its value.

If the Internationalization (i18n) plugin is installed, it's possible to use POST requests to the Content API to create localized entries.

Example request

POST http://localhost:1337/api/restaurants

{
  "data": {
    "title": "Hello",
    "relation": 2,
    "relations": [2, 4],
    "link": {
      "id": 1,
      "type": "abc"
    }
  }
}

Example response

{
  "data": {
    "id": 1,
    "attributes": { … },
    "meta": {}
  },
  "meta": {}
}

# 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 if you want to clear them.

Example request

PUT http://localhost:1337/api/restaurants/1

{
  "data": {
    "title": "Hello",
    "relation": 2,
    "relations": [2, 4],
  }
}

Example response

{
  "data": {
    "id": 1,
    "attributes": {},
    "meta": {}
  },
  "meta": {}
}

✏️ NOTE

If the Internationalization (i18n) plugin is installed, it's currently not possible to update the locale of an entry.

# Delete an entry

Deletes an entry by id and returns its value.

Example request

DELETE http://localhost:1337/api/restaurants/1

Example response

{
  "data": {
    "id": 1,
    "attributes": {},
    "meta": {}
  },
  "meta": {}
}

← GraphQL API →