Custom Return in WEB API

Question

Good afternoon.

I would like to know if there is any standard or good practice (independent of the programming language), for building Web API that allow customization of the content of the response, by the client (user of this API).

Example: A web API with the following resource: http://application/api/clients/100

that would return a JSON in the pattern:

{
    "id": "100",
    "nome": "nome do cliente 100",
    "endereco": "endereço completo do cliente 100"
}

Now imagine that in a particular client of this API, there is a functionality to assemble a client table, where it is necessary to list only the attributes "id" and "name".

A hypothetical solution would be to create another method in the API that returns only the required data. This would prevent the transfer of unnenessary data (in this case the field "address").

However, it does not seem like a good idea to be clogging the API with such specific methods, according to the needs of the clients of this API.

Against this background, the question then is, is there any standard for customizing this return by the customer?

Answer 1

Usually the API returns a lot of stuff, and many of them we don’t use. You can plug up your parameter API or you can simply return everything. I see no problem in returning unnecessary data, unless it’s something the customer really can’t see.

Answer 2

If there is any pattern I do not know, but this is quite simple to implement. You just need to have well defined how you will know when you decide to return one or another format.

See an example, where validate if the logged-in user is of the type UsuarioComum, if yes, all entity data is returned, otherwise only Id and Nome.

public IHttpActionResult Get(int id)
{       
    if(usuarioLogado.Tipo == TipoUsuario.UsuarioComum)
    {
        var retorno = _db.Clientes.Find(id)
                                  .Select(c => new 
                                               {
                                                    c.Id,
                                                    c.Nome,
                                                    c.Endereco
                                               });
        return Ok(retorno);
    }

    var retorno = _db.Clientes.Find(id)
                              .Select(c => new 
                                           {
                                               c.Id,
                                               c.Nome
                                           });
    return Ok(retorno);

}