Ejemplos de API REST para Jitterbit App Builder

Introducción

Los ejemplos en esta página demuestran solicitudes y respuestas de API REST de ejemplo. Asumen un servicio web con el siguiente punto de conexión de API:

http://example.com/Vinyl/rest/v1/sales

Además, asumen que existe un recurso en el siguiente punto de conexión:

http://example.com/Vinyl/rest/v1/sales/customers

El recurso contiene los siguientes campos.

Campo	Incluir por defecto
`customerId`	Verdadero
`companyName`	Verdadero
`contactName`	Verdadero
`contactTitle`	Verdadero
`address`	Falso
`city`	Falso
`region`	Falso
`postalCode`	Falso
`phone`	Falso

Recuperar los primeros diez clientes

Este ejemplo demuestra cómo devolver el primer conjunto de diez clientes. Por defecto, App Builder devolverá diez elementos.

Solicitud

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. Por defecto, App Builder devolverá diez. El número máximo de elementos que se pueden devolver a la vez es 100.

Solicitud

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 navegar por la lista de clientes, recuperando la segunda página de cinco clientes.

Solicitud

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 cliente seleccionados

Este ejemplo demuestra cómo devolver una lista de clientes con campos seleccionados. En este caso, los campos se limitan a customerId, companyName y country.

Solicitud

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 de cliente

Este ejemplo muestra cómo recuperar una lista de clientes que incluye todos los campos de cliente disponibles.

Solicitud

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 de clientes ordenada

Este ejemplo demuestra cómo recuperar una lista de clientes ordenada de forma descendente por país y ascendente por nombre de empresa.

Solicitud

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 el número total de elementos en la colección. Por defecto, App Builder no devolverá el total.

Solicitud

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.

Solicitud

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 POST a la colección de clientes.

Solicitud

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.

Solicitud

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 POST a un elemento de la colección.

Solicitud

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.

Solicitud

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-Vinyl-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. Ten en cuenta que el registro del cliente eliminado se devuelve en la respuesta. Un intento posterior de eliminar el cliente devolvería un 404 ya que el cliente ya no existe.

Solicitud

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
}

Invocar un evento personalizado en un cliente

Este ejemplo demuestra cómo invocar un evento personalizado, SendWelcomeEmail, definido en el objeto de negocio del cliente. Invocar el evento lo ejecuta junto con cualquier acción asociada, como operaciones de datos, notificaciones o validaciones. Dado que este evento solo envía una notificación y no modifica el registro, la respuesta devuelve los datos del cliente sin cambios. El segmento (SendWelcomeEmail) no distingue mayúsculas de minúsculas; (sendwelcomeemail), (SENDWELCOMEEMAIL) y (SendWelcomeEmail) invocan el mismo evento.

Solicitud

POST /rest/v1/sales/customers(SendWelcomeEmail)/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
}