Saltar al contenido

Ejemplos de API REST para Jitterbit App Builder

Los ejemplos en esta página demuestran solicitudes y respuestas de API REST de muestra. Suponen un servicio web con el siguiente punto final de API:

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

Además, suponen que existe un recurso en el siguiente punto final:

  • 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 paginar a través de 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 seleccionados de clientes

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

Request

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

Response

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 clientes

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

Request

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

Response

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 la empresa.

Request

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

Response

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 conteo 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.

Request

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

Response

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.

Request

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

Response

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

Request

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"
}

Response

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.

Request

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

Response

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 haciendo un POST al 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 provoca un error de validación. En este caso, el código de estado HTTP 400 indica que la operación no se completó con éxito.

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. Tenga en cuenta que el registro del cliente eliminado se devuelve en la respuesta. Un intento posterior de eliminar al 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
}