Document Service API: Usage with Draft & Publish#
Use the status parameter with the Document Service API to retrieve published or draft versions of documents, count documents by status, and directly publish documents during creation or updates.
By default the Document Service API returns the draft version of a document when the Draft & Publish feature is enabled. This page describes how to use the status parameter to:
- return the published version of a document,
- count documents depending on their status,
- and directly publish a document while creating it or updating it.
To select documents by how their draft and published versions relate (never-published, modified, and others), see Document Service API: publicationFilter.
Get the published version with findOne() {#find-one}#
await strapi.documents('api::restaurant.restaurant').findOne({
documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
status: 'published'
});
{
documentId: "a1b2c3d4e5f6g7h8i9j0klm",
name: "Biscotte Restaurant",
publishedAt: "2024-03-14T15:40:45.330Z",
locale: "en", // default locale
// …
}
Get the published version with findFirst() {#find-first}#
const document = await strapi.documents("api::restaurant.restaurant").findFirst({
status: 'published',
});
{
documentId: "a1b2c3d4e5f6g7h8i9j0klm",
name: "Biscotte Restaurant",
publishedAt: "2024-03-14T15:40:45.330Z",
locale: "en", // default locale
// …
}
Get the published version with findMany() {#find-many}#
const documents = await strapi.documents("api::restaurant.restaurant").findMany({
status: 'published'
});
[
{
documentId: "a1b2c3d4e5f6g7h8i9j0klm",
name: "Biscotte Restaurant",
publishedAt: "2024-03-14T15:40:45.330Z",
locale: "en", // default locale
// …
}
// …
]
count() only draft or published versions {#count}#
To take into account only draft or published versions of documents while counting documents with the Document Service API, pass the corresponding status parameter:
// Count draft documents (also actually includes published documents)
const draftsCount = await strapi.documents("api::restaurant.restaurant").count({
status: 'draft'
});
// Count only published documents
const publishedCount = await strapi.documents("api::restaurant.restaurant").count({
status: 'published'
});
Create a draft and publish it {#create}#
await strapi.documents('api::restaurant.restaurant').create({
data: {
name: "New Restaurant",
},
status: 'published',
})
{
documentId: "d41r46wac4xix5vpba7561at",
name: "New Restaurant",
publishedAt: "2024-03-14T17:29:03.399Z",
locale: "en" // default locale
// …
}
Update a draft and publish it {#update}#
await strapi.documents('api::restaurant.restaurant').update({
documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
data: {
name: "Biscotte Restaurant (closed)",
},
status: 'published',
})
{
documentId: "a1b2c3d4e5f6g7h8i9j0klm",
name: "Biscotte Restaurant (closed)",
publishedAt: "2024-03-14T17:29:03.399Z",
locale: "en" // default locale
// …
}