REST API Examples¶

The examples on this page demonstrate sample REST API requests and responses. They assume a web service with the following API endpoint:

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

They further assume that a resource exists at the following endpoint:

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

The resource contains the following fields.

Field	Include by Default
customerId	True
companyName	True
contactName	True
contactTitle	True
address	False
city	False
region	False
postalCode	False
phone	False

Retrieve the first ten customers¶

This example demonstrates how to return the first set of ten customers. By default, Vinyl will return ten items.

Request¶

GET /rest/v1/sales/customers 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
}

Retrieve the first five customers¶

This examples demonstrates how to control how many items are returned at a time. By default, Vinyl will return ten. The maximum number of items that can be returned at a time is 100.

Request¶

GET /rest/v1/sales/customers?$limit=5 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"
    },
    ... 4 additional items excluded for brevity ...
  ],
  "message": null,
  "validations": [],
  "status": 200
}

Retrieve the next five customers¶

This example demonstrates how to page through the list of customers, retrieving the second page of five customers.

Request¶

GET /rest/v1/sales/customers?$limit=5&$offset=5 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"
    },
    ... 4 additional items excluded for brevity ...
  ],
  "message": null,
  "validations": [],
  "status": 200
}

Retrieve select customer fields¶

This example demonstrates how to return a list of customers with select fields. In this case, the fields are limited to customerId, companyName and 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
}

Retrieve all customer fields¶

This example shows how to retrieve a list of customers which includes all available customer fields.

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
}

Retrieve sorted list of customers¶

This example demonstrates how to retrieve a list of customers sorted descending by country and ascending by company name.

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
}

Include a count of all customers¶

This example demonstrates how to include the total number of items in the collection. By default, Vinyl will not return the 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
}

Retrieve a list of customers by country¶

This example demonstrates how to limit the list of customers by country.

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
}

Create a new customer¶

This example demonstrates how to create a new customer by POSTing to the customers collection.

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
}

Retrieve an existing customer¶

This example demonstrates how to retrieve an existing customer from the customers collection.

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
}

Update an existing customer¶

This example demonstrates how to update an existing customer by POSTing to the collection item.

Request¶

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

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
}

Update an existing customer with a validation error¶

This example demonstrates how Vinyl responds when an update triggers a validation error. In this case, the HTTP 400 status code indicates that the operation did not complete successfully.

Request¶

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

Response¶

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
}

Delete an existing customer¶

This example demonstrates how delete an existing customer from the collection. Note that the deleted customer record is returned in the response. A subsequent attempt to delete the customer would return a 404 since the customer no longer exists.

Request¶

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

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
}