Migrate from jsonapi-serializer to Alba gem

Home Tickets Migrate from jsonapi-serializer to Alba gemEdit

Cancel

Title *

Priority

Ticket type

Project *

Parent Ticket

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

## 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

Working memory

Pull request url