Strapi 5 Improves Developer Experience with Cleaner API, Document Service API, and Plugin SDK

With Strapi 5, we’ve made some key updates that will help you work more efficiently. Yesterday, we introduced the new Draft & Publish and Content History features that will save a lot of time for marketers. Today, we're excited to share what we have done to improve the developer experience by removing unnecessary complexity.In this post, I’ll walk you through the biggest updates: a cleaner API response format, a new Document Service API, and the long-term support plan.

Let’s dive in.

A Cleaner API Response Format in Strapi 5

Strapi 5 simplifies the Content API response, offering a much cleaner and more intuitive structure compared to Strapi v4. The key improvement here is the flattening of the response format. In Strapi v4, content-type attributes were nested inside the data.attributes object, making API interactions slightly more cumbersome and requiring extra steps to extract necessary data. We have listened to your feedback and in Strapi 5, this nesting has been removed, and attributes are now directly accessible at the first level of the data object.

For example, in Strapi v4, to retrieve the title of a content-type, you’d have to access it like this:

1{
2  "data": {
3    "id": 1,
4    "attributes": {
5      "title": "My First Blog Post"
6    }
7  }
8}

In Strapi 5, the same title attribute can now be accessed directly:

1{
2  "data": {
3    "id": 1,
4    "title": "My First Blog Post"
5  }
6}

This change reduces the complexity of parsing API responses, improves performance, and provides a more intuitive experience for you when working with the Content API. Whether you are working with REST or GraphQL, this flattened structure ensures that your API responses are more concise and readable.

This improvement is especially valuable for large-scale applications where API calls are frequent, and optimization is key to maintaining performance. Removing unnecessary nesting cuts down payload size and processing time, providing smoother, faster interactions with your content API.

Introducing the New Document Service API in Strapi 5

Strapi 5 takes content management a step further with the introduction of a new Document Service API. This API conceptually shifts how content is handled and structured at the API level, giving developers more flexibility and control over content variations without adding complexity for end users in the admin panel.

What is a Document?

In Strapi 5, a document represents all variations of content for a specific entry of a content-type. Documents are now an API-specific concept, designed to manage the various versions of content, such as drafts, published content, and localized variations, all within a unified structure.

For instance, a single entry in a collection type can contain several versions of content based on different locales (e.g., English, French) and publication statuses (e.g., draft, published). Each of these variations belongs to a document that can be uniquely identified and manipulated using its documentId.

This structure allows developers to:

• Retrieve different content variations for a single entry based on locales or publication states.
• Update specific versions of content (such as updating only the draft version without affecting the published one).
• Create, retrieve, update, and delete documents or subsets of data they contain, offering a high degree of flexibility.

How Documents Work in Practice

Let's say you have a blog post content-type. In Strapi 5, when you create a blog post in two locales (English and French), the system generates a document that contains all variations of that entry. This document could include:

• The draft version of the blog post in English.
• The published version of the blog post in English.
• The draft version of the blog post in French.
• The published version of the blog post in French.

All these variations are housed in a single document, identified by a unique documentId. The Document Service API allows you to interact with these variations in a much more granular way, giving you the flexibility to target specific content versions for manipulation.

Document Service API: Key Features

Using the Document Service API, you can programmatically manage content versions with a high degree of precision. Here's a breakdown of how the API typically responds:

• Single Document Response: If you’re working with a single document, the response includes:
  • id: The internal ID of the document.
  • documentId: A unique identifier for that document.
  • attributes: An object containing the actual content (e.g., title, body, etc.).
  • meta: Metadata about the document, such as pagination details or locale info.

1{
2  "data": {
3    "id": 1,
4    "documentId": "abc123",
5    "title": "My First Blog Post",
6    "meta": {
7      "locale": "en",
8      "status": "published"
9    }
10  }
11}

• List of Documents Response: When querying multiple documents, the response contains an array of document objects, each representing a different version of the content:

1{
2  "data": [
3    {
4      "id": 1,
5      "documentId": "abc123",
6      "title": "My First Blog Post",
7      "meta": {
8        "locale": "en",
9        "status": "published"
10      }
11    },
12    {
13      "id": 2,
14      "documentId": "xyz456",
15      "title": "Mon Premier Article de Blog",
16      "meta": {
17        "locale": "fr",
18        "status": "draft"
19      }
20    }
21  ]
22}

• Custom Responses: Depending on your API calls, the response may also include custom objects or metadata related to your specific content models.

The Power of Document Manipulation

The Document Service API gives developers robust tools to handle various scenarios like:

• Localized Content: Easily manage different language versions of the same content without having to create entirely separate entries.
• Draft and Published Versions: Control the draft and published states of content, updating one without affecting the other.
• Granular Content Updates: Target specific subsets of data (e.g., only the French version of a draft) for precise updates or deletions.

This new document-based architecture simplifies complex content management needs, making Strapi 5 a powerful choice for developers who require fine-grained control over content variations, while maintaining ease of use for non-technical users through the admin interface.

Introducing the New Plugin SDK in Strapi 5

To share your Strapi plugins with the community or reuse them across multiple projects, you'll want to package and publish them to npm. Doing all that manually can be a pain—handling bundling, dependencies, and compatibility checks. That's where the new Plugin SDK comes in, making it super easy to create an npm package for your plugins. While you can use other methods, the SDK is your go-to solution to get things done fast.

Why Use the SDK?

The new SDK solves a lot of the common headaches in plugin development:

1. Focus on Building, Not Setup: The SDK lets you focus on the plugin itself, without worrying about setting up a Strapi project first. It's separate from Strapi's release cycle, meaning the SDK can update independently, giving you access to the latest tools and best practices without waiting for the next Strapi version.
2. Fewer Dependencies: The old method required installing a bunch of extra dependencies from the Strapi CLI. With the SDK, you get only what you need, making your development environment lighter and faster.
3. Industry-Standard Approach: SDKs are widely used in software development. By introducing our own, we're keeping things in line with what developers are used to, making it easier for anyone familiar with other ecosystems to start building Strapi plugins.
4. No More CLI Complications: Previously, the idea was to let users create commands inside the Strapi CLI itself. This led to issues like circular dependencies. The SDK sidesteps all that by working independently of the core CLI but still offering everything you need to build plugins smoothly.

What Does the SDK Do for You?

The SDK takes care of the heavy lifting, such as:

• Packaging for CommonJS and ES Modules: It ensures your plugin works in different JavaScript environments without extra config.
• Managing Dependencies: By keeping the SDK separate from the Strapi CLI, you avoid installing unnecessary packages.
• Built-in Defaults: The SDK comes with sensible defaults, so you don’t need to set up complex build systems or bundlers. It’s designed to make your life easier.

While you don’t have to use the SDK, it’s highly recommended if you want a quicker, smoother process for creating, packaging, and sharing Strapi plugins.

How to Get Started

Ready to build your first plugin with the SDK? Here's how:

1. Kick Off Your Plugin Project

   Use the SDK's init command to start a new plugin project:

   npx @strapi/sdk-plugin@latest init my-plugin

   This will set up all the files you need to start building your plugin right away.

2. Handy Commands

   Once your project is set up, the SDK gives you several commands to manage your plugin:

   • init [path]: Generates a new plugin at the specified path.
   • build: Compiles your plugin based on your package.json config. You can customize the build with options like:
     • minify: Minimizes file size (default: false).
     • sourcemap: Generates sourcemaps for easier debugging (default: true).
   • watch: Watches for changes and automatically compiles your plugin for live updates during development.
   • watch:link: Recompiles your plugin on changes and pushes updates with yalc. Great for real-time development.
   • verify: Before publishing, use this command to check everything’s working as expected.

Now you're all set to build, package, and share your Strapi plugins with the community! Whether you're developing a new plugin or upgrading an existing one, this new system offers better control, security, and scalability.

In support of Strapi 5, several technology partners, including Mux, Imgix, CKEditor, and Solution Partners such as VirtusLab, Notum have already updated their plugins to ensure full compatibility with the latest version, enabling users to seamlessly integrate advanced features into new Strapi 5 projects.

If you're ready to start building more robust plugins in Strapi 5, now's the time to dive into the new Plugin SDK. With it, plugin development becomes more efficient, organized, and future-proof.

If you want to dive deeper, we recommend this video with Jamie and Ben from the Strapi team.

Join Us for the Strapi 5 Launch Stream and Community Call on October 8th

To celebrate the launch of Strapi 5, we invite you to join us for a special Strapi Stream and community call on October 8th. This is your chance to connect with the team and learn more about what's new in Strapi 5. We'll be covering the latest updates, discussing how to migrate your projects smoothly, and diving into the new Plugin CLI. It's also the perfect opportunity to ask any questions you might have during our open Q&A session.

📅 Date: October 8th

Global Strapi 5 Launch Parties – Join One Near You

To make the launch of Strapi 5 even more special, our global partners are organizing exclusive launch parties around the world. These events are a fantastic opportunity to celebrate the release, network with other Strapi users, and get firsthand insights from our partners. Whether you’re a seasoned Strapi expert or new to the platform, you’ll find great conversations, live demos, and exciting content at these gatherings.

Find a launch party near you and join in the celebrations!

We're Launching Strapi 5 on Product Hunt!

The Strapi 5 launch isn't just happening behind the scenes – we're bringing the excitement to Product Hunt! Be sure to support us by checking out our Product Hunt page, where we'll be showcasing all the new features of Strapi 5, including the powerful Plugin SDK, Draft & Publish, and Content History.

Your feedback and upvotes mean a lot to us as we continue to make Strapi the best headless CMS out there. Let’s make this a launch to remember!

Ready to Experience Strapi 5?

Strapi 5 is all about making things easier for developers. It introduces a cleaner API response, a flexible Document Service API, and a Plugin SDK that simplifies plugin development. These updates cut out complexity and give you more control over your content.

Upgrade to Strapi 5 today and see how it improves your workflow. Just run the command below to get started—it’s that simple!

   npx create-strapi