Ghost Release: 2.2.3

TL;DR

Ghost 2.2.3: API v2 Implementation & Bug Fixes

This release primarily focuses on implementing the new API v2 framework with controllers for various resources like posts, pages, tags, users, webhooks, and more. It also includes important bug fixes for URL attribute calculation and theme download links. The changes lay groundwork for future API improvements while maintaining backward compatibility.

Highlight of the Release

• Implementation of API v2 controllers for posts, pages, tags, users, webhooks, and more
• Fixed URL attribute calculation when requested as the only part of fields filter
• Enhanced API key security by preventing 'Owner' role assignment
• Improved validation framework with support for global validation on defined fields

Migration Guide

No specific migration steps are required for this release. The API v2 implementation maintains backward compatibility with existing API v0.1 endpoints.

If you're a developer working with the Ghost API:

• The API v2 endpoints are being gradually implemented and may not have feature parity with v0.1 yet
• Continue using v0.1 endpoints for production applications until v2 is fully stable
• Consider exploring the new v2 endpoints for future development

Upgrade Recommendations

This is a minor release with important bug fixes and API improvements. All Ghost users should upgrade to benefit from the URL attribute calculation fix and theme download link repair.

How to upgrade:

1. Back up your Ghost installation
2. Follow the standard upgrade process for your installation method (Git, Docker, or direct install)
3. No database migrations are required for this release

The upgrade is recommended for all users, especially those who:

• Use field filters in the API that include only the URL attribute
• Download themes through the admin interface
• Are developing against the Ghost API

Bug Fixes

URL Attribute Calculation

• Fixed 'url' attribute miscalculation when requested as the only part of fields filter
• Added functional tests to cover this bug scenario
• Refactored URL decorating methods for clarity about parameter nature

API Framework Fixes

• Fixed missing return statement in shared validators
• Added handling for empty query options (e.g., ?formats=)
• Added removal of null values in v2 API
• Moved ID mismatch check to global validator
• Moved toJSON call to API v0.1 controller for ownership transfer
• Respected hasUserPermissions & hasAppPermissions in invite model

Admin Interface

• Fixed theme download links in Ghost Admin

New Features

API v2 Implementation

• Added controllers for multiple resources in API v2:
  • Posts and Pages controllers
  • Tags controller
  • Users controller
  • Webhooks controller
  • Slugs controller
  • Settings controller
  • Notifications controller
  • Mail controller
  • Invites controller
  • Subscribers controller
  • Upload controller

Enhanced API Framework

• Added API Key authentication middleware to v2 content API
• Added permission identifier definition capability
• Added API permissions before hook support
• Added support for status code as a function
• Extended shared validator functionality
• Added ability to require properties from request body
• Implemented global validation on defined fields
• Added support for the columns option in findAll queries

Security Improvements

• Prevented API keys from assigning the 'Owner' role to any user or key
• Updated Integration model to use bookshelf relations for better API key handling

Security Updates

API Key Security

• Prevented API keys from assigning the 'Owner' role to any other key or user
• Cleaned up Role model permissible method
• Updated Integration model to use bookshelf relations for better API key handling
• Added API Key auth middleware to v2 content API with proper authentication flow

Performance Improvements

API Optimizations

• Optimized usage of URLs in API v2
• Extracted URL decoration logic to utility in output serializers for posts, pages, users, and tags
• Added test cases for URL usage by child objects (tags of posts)

Database Improvements

• Removed shell:dbhealth from grunt master as Ghost server now handles database migrations automatically

Impact Summary

Ghost 2.2.3 is primarily focused on implementing the new API v2 framework and fixing important bugs. The release adds numerous controllers to the v2 API including posts, pages, tags, users, webhooks, and more, laying the groundwork for future API improvements.

Key bug fixes include resolving URL attribute miscalculation when requested as the only part of fields filter and repairing theme download links in the admin interface. Security is enhanced by preventing API keys from assigning the 'Owner' role.

For most users, this update will be seamless with improved reliability. For developers, this release provides access to new API v2 endpoints and improved validation handling. The changes maintain backward compatibility while building toward a more robust API architecture.

Full Release Notes