Migrate from jsonapi-serializer to Alba gem

Home Epics Migrate from jsonapi-serializer to Alba gemEdit

Cancel

Title *

Project *

Description

## Overview
Replace the jsonapi-serializer gem with the Alba gem for JSON serialization across the Rails API. Alba is a faster, more lightweight JSON serializer for Ruby with better performance characteristics and a simpler API.

## IMPORTANT: Breaking API Change
**This migration involves a BREAKING CHANGE to the API response format.**

- The migration will **drop the JSON:API specification format** (https://jsonapi.org/)
- The API will change from the complex JSON:API structure to simpler plain JSON
- This is a **breaking change** for any API consumers expecting JSON:API format

### Current JSON:API Format (Example):
```json
{
  "data": {
    "id": "1",
    "type": "tickets",
    "attributes": {
      "title": "Fix bug",
      "status": "backlog"
    },
    "relationships": {
      "project": {
        "data": { "id": "2", "type": "projects" }
      }
    },
    "links": {
      "self": "/api/v1/tickets/1"
    }
  }
}
```

### New Plain JSON Format (Example):
```json
{
  "id": 1,
  "title": "Fix bug",
  "status": "backlog",
  "project": {
    "id": 2,
    "name": "My Project"
  }
}
```

### Impact:
- All API consumers (MCP agents, frontend clients, external integrations) must be updated
- Response parsing logic must change to expect plain JSON objects
- The `data` wrapper, `type` field, and separated `attributes`/`relationships` will be removed
- Nested relationships will be included directly in the response rather than as separate structures

### Consumers That Will Need Updates:
- MCP agent implementations (tinker-worker, tinker-reviewer, tinker-orchestrator)
- Any frontend consuming the API
- External API integrations
- API client tests expecting JSON:API format

## Current State
- Gem: `jsonapi-serializer` (line 29 in /rails/Gemfile)
- 7 serializer files in /rails/app/serializers/:
  - TicketSerializer (most complex, with relationships, computed attributes, links)
  - ProjectSerializer
  - AgentSerializer
  - CommentSerializer
  - CodeDiffSerializer
  - AgentMemorySerializer
  - ArtifactSerializer
- API controllers use `render_jsonapi` and `render_jsonapi_collection` helper methods in BaseController

## Migration Scope
This migration involves:

1. **Gem replacement**: Update Gemfile to use `alba` instead of `jsonapi-serializer`
2. **Serializer conversion**: Convert all 7 serializers from JSONAPI::Serializer format to Alba format
3. **Controller updates**: Modify BaseController helper methods (`render_jsonapi`, `render_jsonapi_collection`) for Alba serialization
4. **API contract change**: Response format changes from JSON:API spec to plain JSON
5. **Consumer updates**: Update all API consumers to handle plain JSON responses

## Key Differences to Address
- Alba uses a different attribute definition syntax
- Alba's relationship handling differs (has_many, belongs_to)
- Conditional attributes require different approach
- Link generation syntax is different in Alba
- Collection serialization has different API
- **Response structure is plain JSON, not JSON:API format**

## Dependencies
- Test suite should be updated to verify Alba serialization produces plain JSON
- All API consumers (MCP agents) must be updated to parse plain JSON
- Consider adding API versioning if backward compatibility is needed

## Files to Modify
- /rails/Gemfile
- /rails/app/serializers/*.rb (7 files)
- /rails/app/controllers/api/v1/base_controller.rb
- MCP agent code consuming the API (separate project/tickets)

## Risk Assessment
- **HIGH Risk**: Breaking API change will break all existing consumers
- **Mitigation**: 
  - Comprehensive test coverage before deploying
  - Coordinate deployment with API consumer updates
  - Consider feature flag or API versioning if gradual rollout needed
  - Document new response format clearly