Field Masks

Field Masks em Web APIs

Definição e Uso:

Field Masks são usados para especificar um subconjunto de campos de um recurso que devem ser retornados ou atualizados em uma operação de API. Eles são particularmente úteis para otimizar o tráfego de rede e o desempenho, permitindo que clientes e servidores se concentrem apenas nos dados relevantes.

Field Masks não devem ser passados no body da requisição. Devem ser passados no headers ou em query strings. Query strings é o mais comum.

Exemplo:

/ChatRoom/1?fieldMask=title&fieldMask=description

Aplicação em Operações de API:

Em uma operação de GET, um Field Mask pode limitar os campos do recurso que são retornados na resposta. Por exemplo, ao solicitar um usuário com /users/123?fieldMask=name,email, apenas o nome e o e-mail do usuário são retornados, ignorando outros campos como endereço ou telefone.

Em uma operação de PATCH ou UPDATE, Field Masks determinam quais campos do recurso devem ser atualizados. Por exemplo, ao atualizar um usuário com um Field Mask de name, apenas o nome do usuário será atualizado, mesmo que o corpo da requisição contenha outros campos.

Formato e Estrutura:

Field Masks são tipicamente representados como uma lista de strings de campos, passados como parâmetros de query string na URL da requisição.

• Exemplo: /resource?fieldMask=field1,field2 indica que apenas field1 e field2 do recurso devem ser considerados.

Campos inválidos

Como a evolução das APIs frequentemente resulta na adição ou remoção de campos, não será incomum receber solicitações de campos ausentes, mesmo para recursos estáticos.

• A abordagem recomendada é ignorar esta solicitação:
  • Na verdade, isso é o mesmo que assumir que o consumidor da API está tratando o recurso como dinâmico e solicitando a indefinição de um campo que não está definido).
  • Fornecer um erro resultaria em um comportamento diferenciado para campos ausentes em recursos dinâmicos e estáticos. Isso tornaria a API desnecessariamente complexa e inconsistente.

Trabalhando com Estruturas Aninhadas:

Field Masks podem ser usados para acessar campos aninhados dentro de estruturas de dados complexas.

• Por exemplo, address.city pode ser usado para acessar o campo city dentro do campo address de um recurso.

Uso com Arrays e Campos Repetidos:

Ao trabalhar com arrays ou campos repetidos, Field Masks podem ser utilizados para especificar que todos os elementos de um array devem ser incluídos. Por exemplo, items.* em uma lista de pedidos pode incluir todos os itens de cada pedido.

NÃO assuma que a ordem dos dados é (ou permanecerá) sempre estável.

• A API NÃO deve fornecer meios de acesso ao “item no índice 0”.
• Isto simplifica significativamente a evolução e manutenção da API

Dados em campos repetidos podem ser representados em Field Masks:

• employees.* ⇒ Todos os empregados
• employees.*.name ⇒ Nomes de todos os empregados

Valores Padrão e Exclusões:

Por padrão, se nenhum Field Mask for especificado, todos os campos de um recurso são incluídos. No entanto, em alguns casos, pode ser preferível omitir campos extensos ou de difícil cálculo por padrão.

Os Field Masks também podem ser usados para excluir campos específicos ao invés de incluí-los.

Exemplo de Exclusão em uma Operação GET:

• Suponha que temos um recurso Employee com os campos name, email, salary, e department.
• Uma requisição GET comum sem Field Mask retornaria todos os campos: /employees/123.
• Agora, digamos que queremos excluir o campo salary por motivos de privacidade.
• Podemos ter uma convenção na API onde prefixamos o nome do campo com um - para indicar exclusão: /employees/123?fieldMask=-salary.
• A resposta incluiria name, email, e department, mas omitiria salary.

Exemplo de Exclusão em uma Operação PATCH/UPDATE:

• Considerando o mesmo recurso Employee, uma operação PATCH ou UPDATE normalmente atualizaria os campos especificados no corpo da requisição.
• Se quisermos garantir que o campo salary não seja atualizado, mesmo que esteja presente no corpo da requisição, podemos usar um Field Mask de exclusão: PATCH /employees/123?fieldMask=-salary.
• Mesmo que o corpo da requisição contenha um novo valor para salary, este campo será ignorado, e apenas os outros campos (se presentes) serão atualizados.

Considerações Adicionais:

É importante notar que a implementação de Field Masks para exclusão de campos é uma decisão de design da API. Não é um padrão universalmente adotado, e diferentes APIs podem ter abordagens diferentes para lidar com a exclusão de campos. A documentação da API deve claramente especificar como os Field Masks funcionam, especialmente no que diz respeito à inclusão e exclusão de campos.

Manipulação de Campos Dinâmicos:

Em recursos com estruturas de dados dinâmicas, Field Masks podem ser usados para gerenciar campos que podem mudar com o tempo, permitindo flexibilidade na manutenção e evolução da API.

Implementação:

A implementação de Field Masks requer que o servidor analise a lista de campos fornecida e aplique a lógica correspondente para incluir ou excluir campos na resposta ou na atualização do recurso.

Considerações de Design:

Ao projetar APIs com Field Masks, é importante considerar a experiência do usuário e garantir que a API seja intuitiva e fácil de usar. Documentação clara e exemplos são essenciais para ajudar os usuários a entender como usar Field Masks efetivamente.

Em resumo, Field Masks são uma ferramenta poderosa em Web APIs para otimizar o tráfego de dados e personalizar as operações de API, permitindo uma interação mais eficiente e focada entre o cliente e o servidor.