Exemplos de API REST

Os exemplos nesta página demonstram solicitações e respostas de API REST de amostra. Eles assumem um serviço da web com o seguinte endpoint da API:

http://example.com/App Builder/rest/v1/sales

Eles ainda assumem que um recurso existe no seguinte endpoint:

http://example.com/App Builder/rest/v1/sales/customers

O recurso contém os seguintes campos.

Campo	Incluir por Padrão
customerId	Verdadeiro
companyName	Verdadeiro
nomeDoContato	Verdadeiro
contatoTitle	Verdadeiro
endereço	Falso
cidade	Falso
região	Falso
postalCode	Falso
telefone	Falso

Recupere os Primeiros Dez Clientes

Este exemplo demonstra como retornar o primeiro conjunto de dez clientes. Por padrão, App Builder retornará dez itens.

Solicitar

GET /rest/v1/sales/customers HTTP/1.1
Host: example.com:443
Accept: application/json
X-API-Key: DLOo9sPS5slJEMHpXBFt3g

Resposta

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 534

{
  "count": null,
  "items": [
    {
      "customerId": "0243783f-7405-4ede-98fb-98b6ce7d71f8",
      "companyName": "Microsoft",
      "contactName": "Satya Nadella",
      "contactTitle": "CEO"
    },
    ... 9 additional items excluded for brevity ...
  ],
  "message": null,
  "validations": [],
  "status": 200
}

Recupere os Primeiros Cinco Clientes

Este exemplo demonstra como controlar quantos itens são retornados por vez. Por padrão, App Builder retornará dez. O número máximo de itens que podem ser retornados por vez é 100.

Solicitar

GET /rest/v1/sales/customers?$limit=5 HTTP/1.1
Host: example.com:443
Accept: application/json
X-API-Key: DLOo9sPS5slJEMHpXBFt3g

Resposta

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 534

{
  "count": null,
  "items": [
    {
      "customerId": "0243783f-7405-4ede-98fb-98b6ce7d71f8",
      "companyName": "Microsoft",
      "contactName": "Satya Nadella",
      "contactTitle": "CEO"
    },
    ... 4 additional items excluded for brevity ...
  ],
  "message": null,
  "validations": [],
  "status": 200
}

Recupere os Próximos Cinco Clientes

Este exemplo demonstra como folhear a lista de clientes, recuperando a segunda página de cinco clientes.

Solicitar

GET /rest/v1/sales/customers?$limit=5&$offset=5 HTTP/1.1
Host: example.com:443
Accept: application/json
X-API-Key: DLOo9sPS5slJEMHpXBFt3g

Resposta

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 534

{
  "count": null,
  "items": [
    {
      "customerId": "0243783f-7405-4ede-98fb-98b6ce7d71f8",
      "companyName": "Apple",
      "contactName": "Tim Cook",
      "contactTitle": "CEO"
    },
    ... 4 additional items excluded for brevity ...
  ],
  "message": null,
  "validations": [],
  "status": 200
}

Recuperar Campos Selecionados do Cliente

Este exemplo demonstra como retornar uma lista de clientes com campos selecionados. Neste caso, os campos são limitados a customerId, companyName e country.

Solicitar

GET /rest/v1/sales/customers?$fields=customerId,companyName,country HTTP/1.1
Host: example.com:443
Accept: application/json
X-API-Key: DLOo9sPS5slJEMHpXBFt3g

Resposta

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 534

{
  "count": null,
  "items": [
    {
      "customerId": "0243783f-7405-4ede-98fb-98b6ce7d71f8",
      "companyName": "Microsoft",
      "country": "USA"
    },
    ... 9 additional items excluded for brevity ...
  ],
  "message": null,
  "validations": [],
  "status": 200
}

Recuperar Todos os Campos do Cliente

Este exemplo mostra como recuperar uma lista de clientes que inclui todos os campos de clientes disponíveis.

Solicitar

GET /rest/v1/sales/customers?$fields=* HTTP/1.1
Host: example.com:443
Accept: application/json
X-API-Key: DLOo9sPS5slJEMHpXBFt3g

Resposta

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 534

{
  "count": null,
  "items": [
    {
      "customerId": "0243783f-7405-4ede-98fb-98b6ce7d71f8",
      "companyName": "Microsoft",
      "contactName": "Satya Nadella",
      "contactTitle": "CEO",
      "address": "One Microsoft Way",
      "city": "Redmond",
      "region": "WA",
      "postalCode": "98052-6399",
      "country": "USA",
      "phone": "555-555-5555"
    },
    ... 9 additional items excluded for brevity ...
  ],
  "message": null,
  "validations": [],
  "status": 200
}

Recuperar Lista Ordenada de Clientes

Este exemplo demonstra como recuperar uma lista de clientes classificados em ordem decrescente por país e crescente por nome da empresa.

Solicitar

GET /rest/v1/sales/customers?$sort=-country,companyName HTTP/1.1
Host: example.com:443
Accept: application/json
X-API-Key: DLOo9sPS5slJEMHpXBFt3g

Resposta

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 534

{
  "count": null,
  "items": [
    {
      "customerId": "0243783f-7405-4ede-98fb-98b6ce7d71f8",
      "companyName": "Apple",
      "contactName": "Tim Cook",
      "contactTitle": "CEO"
    },
    ... 9 additional items excluded for brevity ...
  ],
  "message": null,
  "validations": [],
  "status": 200
}

Incluir uma Contagem de Todos os Clientes

Este exemplo demonstra como incluir o número total de itens na coleção. Por padrão, App Builder não retornará o total.

Solicitar

GET /rest/v1/sales/customers?$count=true HTTP/1.1
Host: example.com:443
Accept: application/json
X-API-Key: DLOo9sPS5slJEMHpXBFt3g

Resposta

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 534

{
  "count": 12429,
  "items": [
    {
      "customerId": "0243783f-7405-4ede-98fb-98b6ce7d71f8",
      "companyName": "Microsoft",
      "contactName": "Satya Nadella",
      "contactTitle": "CEO"
    },
    ... 9 additional items excluded for brevity ...
  ],
  "message": null,
  "validations": [],
  "status": 200
}

Recuperar uma Lista de Clientes por País

Este exemplo demonstra como limitar a lista de clientes por país.

Solicitar

GET /rest/v1/sales/customers?country=USA HTTP/1.1
Host: example.com:443
Accept: application/json
X-API-Key: DLOo9sPS5slJEMHpXBFt3g

Resposta

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 534

{
  "count": null,
  "items": [
    {
      "customerId": "0243783f-7405-4ede-98fb-98b6ce7d71f8",
      "companyName": "Microsoft",
      "contactName": "Satya Nadella",
      "contactTitle": "CEO"
    },
    ... 9 additional items excluded for brevity ...
  ],
  "message": null,
  "validations": [],
  "status": 200
}

Criar um Novo Cliente

Este exemplo demonstra como criar um novo cliente por POST para a coleção de clientes.

Solicitar

POST /rest/v1/sales/customers HTTP/1.1
Host: example.com:443
Accept: application/json
X-API-Key: DLOo9sPS5slJEMHpXBFt3g
Content-Type: application/json

{
  "companyName": "Jitterbit",
  "city": "Miami Beach",
  "region": "FL",
  "postalCode": "33139",
  "country": "USA"
}

Resposta

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 347

{
  "item": {
    "customerId": "9ce33474-8690-4a75-ab90-65caa6c3c24e",
    "companyName": "Jitterbit",
    "contactName": null,
    "contactTitle": null,
    "address": null,
    "city": "Miami Beach",
    "region": "FL",
    "postalCode": "33139",
    "country": "USA",
    "phone": null
  },
  "message": null,
  "validations": [],
  "status": 200
}

Recuperar um Cliente Existente

Este exemplo demonstra como recuperar um cliente existente da coleção de clientes.

Solicitar

GET /rest/v1/sales/customers/9ce33474-8690-4a75-ab90-65caa6c3c24e HTTP/1.1
Host: example.com:443
Accept: application/json
X-API-Key: DLOo9sPS5slJEMHpXBFt3g

Resposta

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 347

{
  "item": {
    "customerId": "9ce33474-8690-4a75-ab90-65caa6c3c24e",
    "companyName": "Jitterbit",
    "contactName": null,
    "contactTitle": null,
    "address": null,
    "city": "Miami Beach",
    "region": "FL",
    "postalCode": "33139",
    "country": "USA",
    "phone": null
  },
  "message": null,
  "validations": [],
  "status": 200
}

Atualizar um Cliente Existente

Este exemplo demonstra como atualizar um cliente existente por meio de POST no item de coleção.

Solicitar

POST /rest/v1/sales/customers/9ce33474-8690-4a75-ab90-65caa6c3c24e HTTP/1.1
Host: example.com:443
Accept: application/json
X-API-Key: DLOo9sPS5slJEMHpXBFt3g
Content-Type: application/json

{
  "companyName": "Jitterbit",
  "city": "Miami Beach",
  "region": "FL",
  "postalCode": "33139",
  "country": "USA"
}

Resposta

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 347

{
  "item": {
    "customerId": "9ce33474-8690-4a75-ab90-65caa6c3c24e",
    "companyName": "Jitterbit",
    "contactName": null,
    "contactTitle": null,
    "address": null,
    "city": "Miami Beach",
    "region": "FL",
    "postalCode": "33139",
    "country": "USA",
    "phone": null
  },
  "message": null,
  "validations": [],
  "status": 200
}

Atualizar um Cliente Existente com um Erro de Validação

Este exemplo demonstra como App Builder responde quando uma atualização dispara um erro de validação. Nesse caso, o código de status HTTP 400 indica que a operação não foi concluída com sucesso.

Solicitar

POST /rest/v1/sales/customers/9ce33474-8690-4a75-ab90-65caa6c3c24e HTTP/1.1
Host: example.com:443
Accept: application/json
X-API-Key: DLOo9sPS5slJEMHpXBFt3g
Content-Type: application/json

{
  "contactName": "This contact name is longer than permitted."
}

Resposta

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8
X-App Builder-Version: 0.0.0
Date: Wed, 26 Oct 2016 19:11:55 GMT
Content-Length: 347

{
  "item": {
    "customerId": "9ce33474-8690-4a75-ab90-65caa6c3c24e",
    "companyName": "Jitterbit",
    "contactName": "This contact name is longer than permitted.",
    "contactTitle": null,
    "address": null,
    "city": "Miami Beach",
    "region": "FL",
    "postalCode": "33139",
    "country": "USA",
    "phone": null
  },
  "message": "The changes could not be saved.",
  "validations": [
    {
      "message": "ContactName has exceeded length of 30 by 13 characters.",
      "severity": "error",
      "field": "contactName"
    }
  ],
  "status": 200
}

Excluir um Cliente Existente

Este exemplo demonstra como excluir um cliente existente da coleção. Observe que o registro do cliente excluído é retornado na resposta. Uma tentativa subsequente de excluir o cliente retornaria um 404, pois o cliente não existe mais.

Solicitar

DELETE /rest/v1/sales/customers/9ce33474-8690-4a75-ab90-65caa6c3c24e HTTP/1.1
Host: example.com:443
Accept: application/json
X-API-Key: DLOo9sPS5slJEMHpXBFt3g
Content-Type: application/json

Resposta

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 347

{
  "item": {
    "customerId": "9ce33474-8690-4a75-ab90-65caa6c3c24e",
    "companyName": "Jitterbit",
    "contactName": null,
    "contactTitle": null,
    "address": null,
    "city": "Miami Beach",
    "region": "FL",
    "postalCode": "33139",
    "country": "USA",
    "phone": null
  },
  "message": null,
  "validations": [],
  "status": 200
}