Estamos lançando uma nova API REST e eu queria algumas sugestões da comunidade sobre práticas recomendadas sobre como deveríamos ter os parâmetros de entrada formatados:
No momento, nossa API é muito centrada em JSON (retorna apenas JSON). O debate sobre se queremos / precisamos retornar XML é uma questão separada.
Como nossa saída de API é centrada em JSON, seguimos um caminho em que nossas entradas são um pouco centradas em JSON e eu estive pensando que pode ser conveniente para alguns, mas estranho em geral.
Por exemplo, para obter alguns detalhes do produto em que vários produtos podem ser extraídos de uma só vez, atualmente temos:
http://our.api.com/Product?id=["101404","7267261"]
Devemos simplificar isso como:
http://our.api.com/Product?id=101404,7267261
Ou a entrada JSON é útil? Mais dor?
Podemos aceitar os dois estilos, mas essa flexibilidade realmente causa mais confusão e dores de cabeça (manutenção, documentação etc.)?
Um caso mais complexo é quando queremos oferecer contribuições mais complexas. Por exemplo, se queremos permitir vários filtros na pesquisa:
http://our.api.com/Search?term=pumas&filters={"productType":["Clothing","Bags"],"color":["Black","Red"]}
Não queremos necessariamente colocar os tipos de filtro (por exemplo, productType e color) como nomes de solicitação como este:
http://our.api.com/Search?term=pumas&productType=["Clothing","Bags"]&color=["Black","Red"]
Porque queríamos agrupar todas as entradas de filtro.
No final, isso realmente importa? Pode ser que haja tantos utilitários JSON por aí que o tipo de entrada simplesmente não importe muito.
Sei que nossos clientes JavaScript que fazem chamadas AJAX para a API podem apreciar as entradas JSON para facilitar sua vida.
[]
sintaxe nem sempre é suportada (e, apesar de comum, pode até violar a especificação do URI). Alguns servidores HTTP e linguagens de programação preferem apenas repetir o nome (por exemploproductType=value1&productType=value2
).