Ghost Release: 2.2.0

TL;DR

Ghost 2.2.0 introduces significant architectural changes to prepare for API v2, adds session-based authentication, and improves error handling. This release focuses on internal restructuring rather than user-facing features, laying groundwork for future functionality with new database tables for sessions, API keys, and mobiledoc revisions. While mostly under-the-hood changes, the release includes an important bug fix for routes.yaml handling.

Highlight of the Release

• Preparation for API v2 with restructuring of API controllers
• New session-based authentication system
• API key authentication capabilities
• Fixed critical bug with routes.yaml handling
• Database migrations for sessions, API keys, and mobiledoc revisions

Migration Guide

API Changes

If you're directly accessing Ghost's API or have custom integrations:

• The API v0.1 is now officially deprecated, though still functional
• API controllers have been moved to api/v0.1/ folder
• Model serialization has changed - the API layer now handles JSON serialization instead of the model layer
• If you're using direct requires of API files in custom code, update paths to require from api/v0.1/

Authentication Changes

This release introduces new authentication mechanisms:

• Session-based authentication
• API key authentication with integration support

These changes are mostly internal preparations and shouldn't require immediate action from most users.

Database Migrations

This release includes several database migrations that will run automatically:

• New session table for storing user sessions
• New integrations and api_keys tables
• New mobiledoc_revisions schema

Ensure you have a backup of your database before upgrading.

Upgrade Recommendations

This is primarily an architectural update preparing for future functionality, with one important bug fix for routes.yaml handling.

• For most users: Standard upgrade is recommended at your convenience.
• For developers with custom code: If you have custom code that directly interacts with Ghost's internal API, review the API restructuring changes.
• For sites using routes.yaml: Upgrade is recommended to fix the issue with unknown taxonomies causing the blog to become unresponsive.

As always, back up your database before upgrading. The database migrations in this release are significant but should run automatically without issues.

Bug Fixes

Fixed Issues

• Fixed critical bug where blog would become unresponsive when uploading routes.yaml with unknown taxonomy
• Instead of returning a 500 error, the system now sends back a proper error message indicating the invalid taxonomy
• Updated API.http handling of controller-returned functions to ensure they're always called regardless of method
• Corrected test suites to properly serialize fetched models to JSON

New Features

API Restructuring for v2

• Moved API controllers into api/v0.1 folder as preparation for v2
• Marked API v0.1 as deprecated and v2 as active
• Added empty API v2 structure with shared folder
• Updated web/ to use API config with new getApiPath method

Authentication Improvements

• Created session table migration for storing user sessions
• Added Session model with relations and unit tests
• Implemented session authentication service with middleware
• Set up schema and models for API Key authentication
• Added integrations and api_keys tables
• Created Integration and ApiKey models

Other Enhancements

• Added mobiledoc_revisions schema and migration script
• Updated base model destroy function to be more generic
• Added command support for index to wrapper

Security Updates

No specific security fixes were mentioned in this release.

Performance Improvements

API Layer Improvements

• Removed toJSON serialization in findPage method
• Added JSON serialization on API layer instead of model layer
• Decoupled model and API layers - all model actions now return raw data without specific formatting
• Removed absolute_urls attribute from validOptions findPage methods as it's no longer needed in the data layer

Model Handling

• Updated base model to be more efficient and generic
• Improved handling of model relations with bookshelf-relations for auto cleanup

Impact Summary

Ghost 2.2.0 represents a significant architectural shift as the project prepares for API v2. While most changes are under-the-hood and won't affect everyday users, developers working with Ghost's internals will notice substantial restructuring.

The API controllers have been moved to a versioned folder structure, with v0.1 now officially deprecated. This sets the stage for the upcoming v2 API. The release also introduces new authentication mechanisms with session-based auth and API key capabilities, adding more flexibility for integrations.

Database migrations add tables for sessions, API keys, integrations, and mobiledoc revisions - all preparing for future functionality. Model serialization has been improved by moving JSON serialization from the model layer to the API layer, creating cleaner separation of concerns.

For site administrators, the most noticeable improvement is the fix for routes.yaml handling, preventing the blog from becoming unresponsive when encountering unknown taxonomies.

Overall, this release focuses on internal improvements rather than user-facing features, laying important groundwork for future enhancements to Ghost.

Full Release Notes