Ejemplos de API REST¶
Los ejemplos de esta página muestran solicitudes y respuestas de API REST de muestra. Suponen un servicio web con el siguiente extremo de API:
http://example.com/App Builder/rest/v1/sales
Además, asumen que existe un recurso en el siguiente extremo:
http://example.com/App Builder/rest/v1/sales/customers
El recurso contiene los siguientes campos.
Campo | Incluir por defecto |
---|---|
IdCliente | Verdadero |
NombreEmpresa | Verdadero |
NombreContacto | Verdadero |
Título del contacto | Verdadero |
Dirección | Falso |
ciudad | Falso |
región | Falso |
Código Postal | Falso |
teléfono | Falso |
Recuperar los Primeros Diez Clientes¶
Este ejemplo demuestra cómo devolver el primer conjunto de diez clientes. De forma predeterminada, App Builder devolverá diez artículos.
Pedido¶
GET /rest/v1/sales/customers HTTP/1.1
Host: example.com:443
Accept: application/json
X-API-Key: DLOo9sPS5slJEMHpXBFt3g
Respuesta¶
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
}
Recuperar los Primeros Cinco Clientes¶
Este ejemplo demuestra cómo controlar cuántos elementos se devuelven a la vez. De forma predeterminada, App Builder se devolverán diez. El número máximo de artículos que se pueden devolver a la vez es 100.
Pedido¶
GET /rest/v1/sales/customers?$limit=5 HTTP/1.1
Host: example.com:443
Accept: application/json
X-API-Key: DLOo9sPS5slJEMHpXBFt3g
Respuesta¶
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
}
Recuperar los Siguientes Cinco Clientes¶
Este ejemplo demuestra cómo recorrer la lista de clientes y recuperar la segunda página de cinco clientes.
Pedido¶
GET /rest/v1/sales/customers?$limit=5&$offset=5 HTTP/1.1
Host: example.com:443
Accept: application/json
X-API-Key: DLOo9sPS5slJEMHpXBFt3g
Respuesta¶
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 de Clientes Seleccionados¶
Este ejemplo demuestra cómo devolver una lista de clientes con campos de selección. En este caso, los campos se limitan a customerId, companyName y country.
Pedido¶
GET /rest/v1/sales/customers?$fields=customerId,companyName,country HTTP/1.1
Host: example.com:443
Accept: application/json
X-API-Key: DLOo9sPS5slJEMHpXBFt3g
Respuesta¶
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 los Campos del Cliente¶
Este ejemplo muestra cómo recuperar una lista de clientes que incluye todos los campos de clientes disponibles.
Pedido¶
GET /rest/v1/sales/customers?$fields=* HTTP/1.1
Host: example.com:443
Accept: application/json
X-API-Key: DLOo9sPS5slJEMHpXBFt3g
Respuesta¶
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 ejemplo demuestra cómo recuperar una lista de clientes ordenada en orden descendente por país y en orden ascendente por nombre de empresa.
Pedido¶
GET /rest/v1/sales/customers?$sort=-country,companyName HTTP/1.1
Host: example.com:443
Accept: application/json
X-API-Key: DLOo9sPS5slJEMHpXBFt3g
Respuesta¶
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 un Recuento de Todos los Clientes¶
Este ejemplo demuestra cómo incluir la cantidad total de elementos en la colección. De manera predeterminada, App Builder no devolverá el total.
Pedido¶
GET /rest/v1/sales/customers?$count=true HTTP/1.1
Host: example.com:443
Accept: application/json
X-API-Key: DLOo9sPS5slJEMHpXBFt3g
Respuesta¶
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 una Lista de Clientes por País¶
Este ejemplo demuestra cómo limitar la lista de clientes por país.
Pedido¶
GET /rest/v1/sales/customers?country=USA HTTP/1.1
Host: example.com:443
Accept: application/json
X-API-Key: DLOo9sPS5slJEMHpXBFt3g
Respuesta¶
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
}
Crear un Nuevo Cliente¶
Este ejemplo demuestra cómo crear un nuevo cliente mediante una publicación en la colección de clientes.
Pedido¶
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"
}
Respuesta¶
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 un Cliente Existente¶
Este ejemplo demuestra cómo recuperar un cliente existente de la colección de clientes.
Pedido¶
GET /rest/v1/sales/customers/9ce33474-8690-4a75-ab90-65caa6c3c24e HTTP/1.1
Host: example.com:443
Accept: application/json
X-API-Key: DLOo9sPS5slJEMHpXBFt3g
Respuesta¶
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
}
Actualizar un Cliente Existente¶
Este ejemplo demuestra cómo actualizar un cliente existente mediante una publicación en el elemento de la colección.
Pedido¶
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"
}
Respuesta¶
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
}
Actualizar un Cliente Existente con un Error de Validación¶
Este ejemplo demuestra cómo App Builder responde cuando una actualización genera un error de validación. En este caso, el código de estado HTTP 400 indica que la operación no se completó correctamente.
Pedido¶
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."
}
Respuesta¶
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
}
Eliminar un Cliente Existente¶
Este ejemplo demuestra cómo eliminar un cliente existente de la colección. Tenga en cuenta que el registro del cliente eliminado se devuelve en la respuesta. Un intento posterior de eliminar el cliente devolvería un error 404, ya que el cliente ya no existe.
Pedido¶
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
Respuesta¶
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
}