Ghost Release: 2.3.0

TL;DR

Ghost 2.3.0 introduces a comprehensive webhooks system, HTTP BREAD API for integrations, and support for different Ghost API versions. This release enhances developer flexibility with new endpoints, improves webhook functionality with better error handling, and refines how the CMS interacts with different API versions. The update is particularly valuable for developers building integrations or working with the Ghost API, as it provides more robust tools for extending Ghost's capabilities.

Highlight of the Release

• New HTTP BREAD API for integrations resource
• Support for different Ghost API versions (v0.1 and v2)
• New site.changed event and webhook trigger service
• Enhanced webhook functionality with better error handling

Migration Guide

Migration Notes

This release contains database migrations to support the new webhooks functionality. Before upgrading:

1. Backup your database: As with any version that includes database migrations, ensure you have a complete backup of your database before upgrading.

2. API Version Considerations: If you have custom themes or integrations that interact with the Ghost API:

   • Be aware that API v2 returns absolute URLs while v0.1 returns relative URLs
   • Check any code that relies on URL formats from the API
   • Update any integrations to work with the new endpoints if necessary

3. Theme Compatibility: If your theme uses custom helpers or relies on specific API behavior:

   • Test with both API versions to ensure compatibility
   • Update any code that might be affected by the changes to the {{get}} helper

Upgrade Recommendations

This is a recommended upgrade for developers working with Ghost integrations or webhooks. The release introduces valuable new API endpoints and webhook functionality that enhances Ghost's extensibility.

For standard Ghost installations without custom integrations or webhooks, this upgrade is optional but recommended to stay current with the latest improvements.

As always, perform a complete backup of your database and files before upgrading, and test the upgrade in a staging environment if possible.

Bug Fixes

Fixed Issues

• Fixed read posts/pages for v2 API to properly handle filters
• Fixed read pages with user access to maintain backward compatibility
• Fixed entry controller to handle both v2 and v0.1 URL response formats (absolute vs relative URLs)
• Fixed a link typo in CONTRIBUTING.md (corrected "github.comc" to "github.com")

New Features

HTTP BREAD API for Integrations

A complete set of API endpoints has been added for managing integrations:

• POST /integrations - Create new integrations
• GET /integrations/:id - Retrieve a specific integration
• GET /integrations - List all integrations
• PUT /integrations/:id - Update an integration
• DELETE /integrations/:id - Remove an integration

Ghost API Version Support

Ghost now supports different API versions with several improvements:

• Default fallback to v0.1
• Support for different response formats
• API version attached to res.locals context for access throughout the request lifecycle
• Updated blog site components to respect the API version dynamically

Enhanced Webhook System

The webhook system received significant enhancements:

• New site.changed event and webhook trigger service
• Improved webhook request headers
• Better error handling with detailed messages for request failures
• Added webhook event information to the payload
• New edit webhook route in v2 Admin API (PUT /webhooks/:id)

Security Updates

No specific security fixes were mentioned in this release.

Performance Improvements

• Refactored webhooks service for better organization and efficiency
• Improved how resources are identified by URL generators, comparing by ID instead of URL format
• Ensured integration model uses transactions for database writes to maintain data integrity

Impact Summary

Ghost 2.3.0 significantly enhances the platform's extensibility and integration capabilities. The new HTTP BREAD API for integrations provides a complete set of endpoints for managing integration resources, making it easier for developers to build and maintain connections with external services.

The support for different Ghost API versions (v0.1 and v2) improves flexibility and backward compatibility, allowing site owners to choose the API version that best suits their needs. This is particularly important for theme developers who need to account for differences in URL formats and available endpoints.

The enhanced webhook system, including the new site.changed event and improved error handling, provides more reliable and informative integration points for external services. The addition of the edit webhook route in the v2 Admin API completes the webhook management capabilities.

These changes primarily impact developers working with Ghost's API and webhooks, while regular users and content creators will likely not notice any significant differences in their day-to-day usage of the platform.

Full Release Notes