Qual é a maneira correta de executar um método de pesquisa RESTful complexo?

Seguindo os princípios REST, gostaria de criar um método GET para minha API que faça uma pesquisa usando alguns critérios e retorne os resultados ao cliente. O problema é que os critérios podem ter até 14 parâmetros, um deles é uma lista de objetos complexos, então ...

• Eu nem sei se é possível codificar / decodificar esses objetos complexos para / de parâmetros de URL.

• Não calculei quanto tempo o URL poderia ficar, mas tenho certeza de que será grande o suficiente e talvez atinja o limite de comprimento do URL.

Além disso, a pesquisa deve mostrar os resultados em "tempo real", ou seja, toda vez que o usuário altera algo do formulário de pesquisa, ele deve poder ver os novos resultados sem pressionar nenhum botão "pesquisar".

Você poderia me esclarecer esses pontos e qual seria o seu conselho para criar um método de pesquisa tranqüilo com muitos parâmetros?

Antes de ler minha resposta, gostaria de dizer que concordei com @Neil. Temos que escolher nossas batalhas. Geralmente, queremos dar o melhor de nós, mas às vezes há muito pouco espaço para discussão e precisamos tomar decisões contra a nossa vontade.

De qualquer forma, na resposta de Neil, sinto falta de mais uma coisa. Documentação . Apenas para garantir que os desenvolvedores saibam que os pedidos do POST /searchsão seguros.

Dito isto.

1. Dê uma chance para GET

Considere a GETopção primeiro. Confira o comprimento máximo do URL desta pergunta . Avalie se sua cadeia de caracteres de consulta mais longa tem mais de 2000 caracteres. Se não, e você não espera, continue GET. Pode parecer feio, mas pelo menos você pode marcar o URL como favorito e, é claro, tem todas as vantagens derivadas da semântica do método (idempotência, segurança e armazenamento em cache)

1.1 Tente codificar a string de consulta

Por exemplo, na base 64. Até o javascript suporta codificações da base 64 .

É assim que funciona:

1. Crie o JSON com todos os filtros e normalize-o.
2. Analise-o como string
3. Codifique
4. Envie o JSON codificado como solicitação param ( /search?q=SGVsbG8gV29ybGQh....).
5. No lado do servidor, decodifique o parâmetro q .
6. Desserializar a sequência JSON

Anteriormente, crie a cadeia JSON mais longa possível, codifique-a e obtenha o comprimento. Avalie se a sequência codificada se encaixa na URL. Eu implementei o seguinte snippet no Fiddle.js para você testar. (Espero que ainda funcione) ¹

Os códigos da base 64 são determinísticos e reversíveis, portanto não há chance de colisões.

Com consultas codificadas, também poderíamos salvar pesquisas no banco de dados, marcar o URL como favorito, compartilhar links etc. E, é claro, não precisamos escapar / tirar o escape da string.

1.2 Tente com aliases

Lendo este blog sobre como criar APIs REST, lembrei-me de mais uma alternativa. Aliases para consultas comuns .

Acho isso interessante pelas próximas razões

• Encurte o comprimento da string de consulta. Torna a API mais limpa e fácil de usar

  GET / tickets /? Status = fechado e fechadoAt = xxx vs GET / tickets / recentemente fechado /

• Combinável com mais aliases ou mais parâmetros de solicitação.

  GET / tickets /? Status = fechado e fechadoAt = xxx e dentro de 30min vs GET / tickets / recentemente fechado /? Within = 30min

• Podemos combinar aliases com cadeias de consulta codificadas

  GET / tickets /? Status = fechado e fechadoAt = xxx e dentro de 30min vs GET / tickets / recentemente fechado /? Q = SGVsbG8g ...

^{1: usei o JSON, mas poderíamos usar outros formatos assim que desserializá-lo no lado do servidor.}

Se tudo o que você tem é um martelo, tudo parece um prego. Parece que o problema aqui é que você está tentando transformar uma página de pesquisa em uma RESTful, e esse dificilmente parece ser um padrão comum para o design RESTful resolver.

Basta ir com uma solicitação POST com os parâmetros fornecidos pelo usuário para obter as informações necessárias no back-end. Suponho que você não precise fazer nada além de realizar uma pesquisa; portanto, não há chance de inserir nesta página. Basta adicionar uma pesquisa / ao final do seu URL para não correr o risco de entrar em conflito com a página / users, que seria RESTful.

Depende totalmente de qual é o seu modelo de API: como nenhum ou como verbo.

Se a API for nenhuma, convém obter a lista de objetos da seguinte maneira:

GET: /api/v1/objects

Nesse caso, você deve enviar dados como parâmetros de solicitação. Portanto, você deve descrever seus parâmetros como uma lista simples de valores-chave:

GET: /api/v1/objects

key1 : val1
key2.key1 : val 21
key2.key2 : val 22
....

Algumas plataformas suportam o resolvedor de parâmetros personalizado (por exemplo, Spring MVC), e você pode converter parâmetros em um objeto.