Overrides

Gerenciamento de overrides para forcar uma variação específica para um usuário.

Endpoints

Método	Endpoint	Descrição	Permissão
POST	/api/v1/feature-flags/:flagId/overrides	Criar override	FEATURE_FLAGS_UPDATE
GET	/api/v1/feature-flags/:flagId/overrides	Listar overrides	FEATURE_FLAGS_READ
GET	/api/v1/feature-flags/:flagId/overrides/:id	Obter override	FEATURE_FLAGS_READ
DELETE	/api/v1/feature-flags/:flagId/overrides/:id	Excluir override	FEATURE_FLAGS_UPDATE

Atributos

Campo	Tipo	Obrigatório	Descrição
userId	string	Sim	ID do usuário para o override (max 255 caracteres)
variationKey	string	Sim	Key da variação a ser forcada

---

Criar Override

POST /api/v1/feature-flags/:flagId/overrides

Cria um override para forcar uma variação específica para um usuário. O override tem prioridade sobre targeting rules.

Request

cURL

curl -X POST 'https://feature-flags.stg.catalisa.app/api/v1/feature-flags/550e8400-e29b-41d4-a716-446655440000/overrides' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "userId": "user-123",
    "variationKey": "on"
  }'

JavaScript

const flagId = '550e8400-e29b-41d4-a716-446655440000';

const response = await fetch(`https://feature-flags.stg.catalisa.app/api/v1/feature-flags/${flagId}/overrides`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    userId: 'user-123',
    variationKey: 'on',
  }),
});

const { data } = await response.json();

Response (201 Created)

{
  "data": {
    "type": "overrides",
    "id": "550e8400-e29b-41d4-a716-446655440005",
    "attributes": {
      "userId": "user-123",
      "variationKey": "on",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    },
    "links": {
      "self": "/api/v1/feature-flags/550e8400-e29b-41d4-a716-446655440000/overrides/550e8400-e29b-41d4-a716-446655440005"
    }
  }
}

---

Listar Overrides

GET /api/v1/feature-flags/:flagId/overrides

Lista todos os overrides de uma feature flag com suporte a paginação.

Query Parameters

Parâmetro	Tipo	Descrição
page[number]	integer	Número da pagina
page[size]	integer	Itens por pagina (max 100)

cURL

curl 'https://feature-flags.stg.catalisa.app/api/v1/feature-flags/550e8400-e29b-41d4-a716-446655440000/overrides' \
  -H 'Authorization: Bearer SEU_TOKEN'

JavaScript

const flagId = '550e8400-e29b-41d4-a716-446655440000';

const response = await fetch(`https://feature-flags.stg.catalisa.app/api/v1/feature-flags/${flagId}/overrides`, {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const { data, meta, links } = await response.json();

Response (200 OK)

{
  "data": [
    {
      "type": "overrides",
      "id": "550e8400-e29b-41d4-a716-446655440005",
      "attributes": {
        "userId": "user-123",
        "variationKey": "on"
      }
    },
    {
      "type": "overrides",
      "id": "550e8400-e29b-41d4-a716-446655440006",
      "attributes": {
        "userId": "user-456",
        "variationKey": "off"
      }
    }
  ],
  "meta": {
    "totalItems": 2,
    "totalPages": 1,
    "currentPage": 1
  },
  "links": {
    "self": "/api/v1/feature-flags/.../overrides?page[number]=1&page[size]=20"
  }
}

---

Obter Override

GET /api/v1/feature-flags/:flagId/overrides/:id

Obtém detalhes de um override específico.

cURL

curl 'https://feature-flags.stg.catalisa.app/api/v1/feature-flags/550e8400-e29b-41d4-a716-446655440000/overrides/550e8400-e29b-41d4-a716-446655440005' \
  -H 'Authorization: Bearer SEU_TOKEN'

JavaScript

const flagId = '550e8400-e29b-41d4-a716-446655440000';
const overrideId = '550e8400-e29b-41d4-a716-446655440005';

const response = await fetch(`https://feature-flags.stg.catalisa.app/api/v1/feature-flags/${flagId}/overrides/${overrideId}`, {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const { data } = await response.json();

Response (200 OK)

{
  "data": {
    "type": "overrides",
    "id": "550e8400-e29b-41d4-a716-446655440005",
    "attributes": {
      "userId": "user-123",
      "variationKey": "on",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    },
    "links": {
      "self": "/api/v1/feature-flags/.../overrides/..."
    }
  }
}

---

Excluir Override

DELETE /api/v1/feature-flags/:flagId/overrides/:id

Remove um override. O usuário passara a ser avaliado normalmente pelas targeting rules.

cURL

curl -X DELETE 'https://feature-flags.stg.catalisa.app/api/v1/feature-flags/550e8400-e29b-41d4-a716-446655440000/overrides/550e8400-e29b-41d4-a716-446655440005' \
  -H 'Authorization: Bearer SEU_TOKEN'

JavaScript

const flagId = '550e8400-e29b-41d4-a716-446655440000';
const overrideId = '550e8400-e29b-41d4-a716-446655440005';

const response = await fetch(`https://feature-flags.stg.catalisa.app/api/v1/feature-flags/${flagId}/overrides/${overrideId}`, {
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

// Status 204 No Content = sucesso

Response (204 No Content)

Sem corpo de resposta.

---

Casos de Uso

Testes de QA

Permite que a equipe de QA teste todas as variações de uma flag:

// QA tester vê variação "on"
await createOverride(flagId, {
  userId: 'qa-user-1',
  variationKey: 'on',
});

// Outro QA tester vê variação "off"
await createOverride(flagId, {
  userId: 'qa-user-2',
  variationKey: 'off',
});

Demo para Stakeholders

Garante que stakeholders vejam a nova feature em demonstracoes:

// CEO sempre vê a nova feature
await createOverride(flagId, {
  userId: 'ceo@company.com',
  variationKey: 'new-feature',
});

Debugging

Permite replicar o comportamento visto por um usuário específico:

// Force variação específica para debugar problema
await createOverride(flagId, {
  userId: 'user-with-issue',
  variationKey: 'problematic-variant',
});

Suporte ao Cliente

Ativa ou desativa features manualmente para usuários com problemas:

// Desativa feature problematica para um usuário
await createOverride(flagId, {
  userId: 'customer-123',
  variationKey: 'legacy-experience',
});

---

Comportamento na Avaliação

Quando uma flag e avaliada para um usuário com override:

1. Override existe? → Retorna a variação do override imediatamente
2. Reason na resposta → OVERRIDE
3. Targeting rules → Não são avaliadas

// Avaliação para user-123 com override
const result = await evaluateFlag('new-checkout-flow', {
  context: { userId: 'user-123' },
});

console.log(result);
// {
//   flagKey: "new-checkout-flow",
//   value: true,
//   variationKey: "on",
//   reason: "OVERRIDE"  <-- indica que veio de override
// }

---

Erros Comuns

Código	Erro	Descrição
400	VALIDATION	Campos obrigatorios ausentes
404	NOT_FOUND	Feature flag ou override nao encontrado
409	CONFLICT	Override ja existe para este usuário nesta flag
400	VALIDATION	variationKey nao existe na flag