Campos solicitados

A funcionalidade de campos solicitados oferece flexibilidade ao permitir a definição de campos específicos a serem incluídos nas respostas das chamadas de API.

Para proporcionar maior flexibilidade na obtenção de dados, a API oferece uma funcionalidade de “campos solicitados”, que permite selecionar campos específicos de retorno. Esta característica é especialmente útil ao trabalhar com campos expandidos, permitindo solicitar apenas os subcampos relevantes.

Pontos importantes

• Na ausência do parâmetro fields, a saída padrão é fornecida.
• Não há limite de profundidade dos campos solicitados.

Como funciona?

Selecionando campos

Adicione o parâmetro fields à sua solicitação para especificar os campos desejados no retorno. Se estiver trabalhando com campos expandidos usando o parâmetro expand, também é possível aplicar a resposta seletiva.

Por exemplo, em uma requisição para buscar informações de um Loan, onde a resposta padrão seria:

curl --request GET \
     --url https://api.dev.base39.io/v1/loans/loan_63ff94f928a4fb05d70b7a17 \
     --header 'accept: application/json' \
     --header 'authorization: Bearer ${api-key}'

{
  "id": "loan_63ff94f928a4fb05d70b7a17",
  "customer":  "cust_63ff98c128a4fb05d70b7a22",
  "employment": "empl_63ff98cf28a4fb05d70b7a25",
  "company": "comp_63ff55cf28a4fb05d70b7a55",
  "status": "open",
  "offer": {
    "disbursementAmount": 1000,
    "fund": "fund_63ff55cf28a4fb05d70b7aa1",
    "rebates": [
      {
        "feeType": "tac",
        "amountType": "absolute",
        "amount": 200
      },
      {
        "feeType": "registration",
        "amountType": "absolute",
        "amount": 150
      },
      {
        "feeType": "spread",
        "amountType": "absolute",
        "amount": 100
      },
    ]
    ...
  }
  ...
}

Por algum motivo, pode ser que o usuário queira somente utilizar os campos id, customer e status. Nesse caso, ao adicionar o queryParameters fields=id,customer,status, teremos:

curl --request GET \
     --url 'https://api.dev.base39.io/v1/loans/loan_63ff94f928a4fb05d70b7a17?fields=id,customer,status' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer ${api-key}'

{
  "id": "loan_63ff94f928a4fb05d70b7a17",
  "customer":  "cust_63ff98c128a4fb05d70b7a22"
  "status": "open",
}

Campos aninhados

Você pode solicitar subcampos de campos expandidos. Utilize o ponto . para navegar entre subdocumentos.

Por exemplo, se quisermos somente os campos id, offer.disbursementAmount e offer.fund, adicionamos ao queryParameters a propriedade fields=id,offer.disbursementAmount,offer.fund. Note que foi utilizado o . para navegar entre subdocumentos.

curl --request GET \
     --url 'https://api.dev.base39.io/v1/loans/loan_63ff94f928a4fb05d70b7a17?fields=id,offer.disbursementAmount,offer.fund' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer ${api-key}'

{
  "id": "loan_63ff94f928a4fb05d70b7a17",
  "offer": {
    "disbursementAmount": 1000,
    "fund": "fund_63ff55cf28a4fb05d70b7aa1"
  }
}

Campos em lista

É possível selecionar uma propriedade comum entre os subdocumentos de uma lista. Por exemplo, para selecionar somente os campos id do loan, e os campos amount e feeType contidos em offer.rebates, basta adicionar ao queryParameters a propriedade fields=id,offer.rebates.feeType,offer.rebates.amount.

curl --request GET \
     --url 'https://api.dev.base39.io/v1/loans/loan_63ff94f928a4fb05d70b7a17?fields=id,offer.rebates.feeType,offer.rebates.amount' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer ${api-key}'

{
  "id": "loan_63ff94f928a4fb05d70b7a17",
  "offer": {
    "rebates": [
      {
        "feeType": "tac",
        "amount": 200
      },
      {
        "feeType": "registration",
        "amount": 150
      },
      {
        "feeType": "spread",
        "amount": 100
      },
    ]
  }
}

Note que, como rebates é uma lista de rebate, então o recurso (campos solicitados) faz uma busca do campo em todos os subdocumentos dessa lista.

Campos expandidos

A funcionalidade “campos solicitados” também possibilita a seleção de campos específicos após a realização de uma expansão de dados.

Por exemplo, suponhamos que haja uma solicitação que expanda o atributo customer dentro de um Loan:

curl --request GET \
     --url 'https://api.dev.base39.io/v1/loans/loan_63ff94f928a4fb05d70b7a17?expand=customer' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer ${api-key}'

{
  "id": "loan_63ff94f928a4fb05d70b7a17",
  "customer":  {
    "id": "cust_63ff98c128a4fb05d70b7a22",
    "name": "João",
    "username": "joao",
    ...
  }
  "employment": "empl_63ff98cf28a4fb05d70b7a25",
  "company": "comp_63ff55cf28a4fb05d70b7a55",
  "status": "open",
  "offer": {
    "disbursementAmount": 1000,
    "fund": "fund_63ff55cf28a4fb05d70b7aa1",
    "rebates": [
      {
        "feeType": "tac",
        "amountType": "absolute",
        "amount": 200
      },
      {
        "feeType": "registration",
        "amountType": "absolute",
        "amount": 150
      },
      {
        "feeType": "spread",
        "amountType": "absolute",
        "amount": 100
      },
    ]
    ...
  }
  ...
}

Esta é a resposta padrão para um campo expandido. No entanto, caso deseje obter somente os campos id e name do customer, você pode incluir ao queryParameters a instrução fields=id,customer.id,customer.nome.

curl --request GET \
     --url 'https://api.dev.base39.io/v1/loans/loan_63ff94f928a4fb05d70b7a17?expand=customer,employment&fields=id,customer.id,customer.nome' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer ${api-key}'

{
  "id": "loan_63ff94f928a4fb05d70b7a17",
  "customer": {
    "id": "cust_63ff98c128a4fb05d70b7a22",
    "name": "João",
  }
}