Getting Started With the API

Basic Concepts

The Quotevine API is an HTTPS RESTful API. This means data is sent and received as a result of standard HTTPS requests. All data is sent and received using JSON.

For an overview of HTTPS see: HTTPS

For an overview of REST see: REST

For an overview of JSON see: JSON

If you are not familiar with JSON or REST, please take the time to read the above before commencing development. We find that Postman is a great tool for debugging REST calls - you can get it from the excellently-named Postman: The World's Leading API Platform | Sign Up for Free .

Note that when sending JSON you must set the Content-Type header of your HTTP request to application/json.

Note that wherever an ID is specified in a URL, this must be the integer ID of the object, not any secondary textual reference.

Access

In order to access the Quotevine API, we must be sure that any request is coming from an authorised application. This is achieved by only granting access to applications which can present a key that could only have been created by an application administrator.

Generating a Key

Only Administrator users can create API Keys. Each key must only be used by one application or environment, so if you have multiple website environments (e.g. dev, UAT, production) each one must have its own key. In order to grant access the following steps need to be performed:

Navigate to the ‘Settings’ menu.
Scroll down to the API Applications area.
Click ‘Add Application’.
Enter a title for your API Application, e.g. Main Website, Kerridge CMS
Click Save and confirm.

This will generate the key, which can then be found in your list of API Applications:

This key then needs to be supplied to your development team.

Revoking a Key

To revoke a key please email support@quotevineapp.com.

URL

The production API is reached at

https://<subdomain>.quotevineapp.com/qvine/quotevine/api/v2

If you do not know your client’s subdomain ask them for their login URL.

Authentication

As an application developer wishing to authenticate with the Quotevine API you must supply the API Key that has been provided to you in each call by populating it into an HTTP header named api-key. If you have difficulty you may wish to use a tool like Fiddler Web Debugging Proxy and Troubleshooting Tools | Fiddler or Postman to ensure your header is correctly set.

Note that UAT and production will require different API keys.

Dates

All dates are output in, and must be supplied in, ISO format: 2013-06-28

or if a time is relevant then 2013-06-28 02:17:26.

Making a Resilient Integration

Quotevine does not keep a record of your requests into the API. Like all systems - at times the API may be unavailable. Therefore you must always record the data you wish to send to the API in the database of the calling application, and implement functionality to periodically resend any failed requests to the API.

Updates

If you are updating an object via the API you must pass ALL populated fields back to the PUT call, not just the field you want to update. Failure to do this will result in data loss for your client. As an example, say the following relationship is read from the API

{
  "relationship_id":357232341,
  "external_reference":"357232341",
  "account_manager":"james.preston@demobroker.com",
  "legal_form":"Limited Company",
  "display_name":"Quotevine Limited",
  "business_description":"SaaS Software Design"
  ...
}

and you want to update the external_reference field. You must pass the following into the PUT call (relationship_id is deliberately omitted as IDs are not passed in for POSTs or PUTs) :

{
  "external_reference":"ABCDEFGH",
  "account_manager":"james.preston@demobroker.com",
  "legal_form":"Limited Company",
  "display_name":"Quotevine Limited",
  "business_description":"SaaS Software Design"
  ...
}

Some key things to note:

A call to the API will always result in either a 200/201 or a 4xx. If you get a 4xx then you will also get an email to the email address specified in your API application.
You need a separate API key for each website/application and environment.
You need to store your API requests before you send them, not only to ensure a great asynchronous experience for users of your website but also so that if they fail or the API is unavailable, you can retry periodically. It also makes debugging a whole heap easier if you store the requests and responses you receive. Only store data locally while the user is interacting with your site, then use a scheduled job mechanism (e.g. Celery) to push data to the API at whatever frequency your client desires.
Postman is a great tool for developing against REST/JSON APIs!

Help

If you come unstuck integrating with the API please email support@quotevineapp.com.