Skip to main content

Topics

Environments​

To make the API as explorable as possible, two environments are available :

  • Preproduction : testing and advanced staging environment, you have to use the preproduction environment before pushing your app to production.
    Use that specific URL for preproduction : http://preprod.winesitting.com
  • Production : real environment, after preproduction validation, you will be able to deploy to production.
    Use that specific URL for production : https://app.winesitting.com
info

In both case you need to ask WineSitting for access to these environments.

URL strategy​

The API endpoints URL are constructed with this following pattern : environment/version/resource/service/{parameters}.

  • environment : environment you want to use.
  • version : the API version you want to use. Current API version is v1
  • resource : the resource path you want to access. A resource is described in this documentation with “API” suffix and can be accessed with a path.
    For example, the Addresses API can be accessed with the resource path /addresses.
  • service : service path you want to use.
    For example, GET /bottles/consolidated let you get your cellar in a consolidated way.
  • parameters : some services require one or more parameters. In this case, the documentation URL contains parameter names surrounded with { and }, and this parameter will be replaced in real case by the value.

Finally, the verb of HTTP method (GET, PUT, POST, DELETE) is necessary to get the complete URL.

Authentication​

Authenticate your account when using the API by including your secret accessKey and secretKey.

You can manage your API keys on WineSitting Dashboard at url https://app.winesitting.com/apiKey. If you don’t have an account, you can contact WineSitting here or by clicking on the chat at the bottom right of you interface.

Your API keys carry many privileges, so be sure to keep them secret ! Do not share your secret API keys in publicly accessible areas such GitHub, client-side code, and so forth.

Then you need to provide the unique ID (accessKey) and the secret key (secretKey) every time you have to request the REST API methods. You need to provide unique ID and secret key by using HTTP Headers, using headers AccessKey and SecretKey.

info

URL parameters or headers are case-sensitive !

Example request with HTTP headers​

$ curl --request GET \
       --url 'https://app.winesitting.com/v1/addresses' \
       --header 'AccessKey: YourAccessKey' \
       --header 'SecretKey: YourSecretKey' \
       --header 'content-type: application/json'
note

Make sure to replace YourAccessKey and YourSecretKey with your API credentials.

Errors​

WineSitting API uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.), and codes in the 5xx range indicate an technical error with WineSitting servers (these are rare).

Each service contains his own specific error codes, and the general error codes are described bellow.

Error nameHTTP status CodeDescription
internal_error500
Internal Server Error		Internal server error
not_found404
Not found		No service found for request URL
not_implemented404
Not found		Not implemented, available in further release
request_content_type_invalid400
Bad Request		Invalid request content type, header “Content-Type” is probably not specified with value “application/json”
access_key_id_missing401
Unauthorized		The Access Key is missing
secret_access_key_missing401
Unauthorized		The Secret Access Key is missing
credentials_invalid401
Unauthorized		Invalid credential, Access Key Id or/and Secret Access Key is/are invalid
not_sufficient_rights_invalid401
Unauthorized		Authenticated API account has not sufficient rights
account_blocked403
Forbidden		Authenticated API account is blocked
invalid_json400
Bad Request		Json request content is not valid

Date and time format​

WineSitting API uses conventional timestamp format. Dates are in Europe/Paris timezone.

Example : 2019-01-23T11:51:35+01:00

Country code format​

WineSitting API uses ISO 3166-1 alpha-2 codes.

Example : France => FR

Content type​

WineSitting API uses JSON for requests and responses, so all HTTP requests must specify content-type header with value application/json.

All JSON responses will be encoded in UTF-8, so response header content-type is defined with value application/json; charset=utf-8.

Pagination​

All top-level API resources have support for bulk fetches via “list” API methods. For instance you can list bottles, addresses, get out requests, invoices, transactions, wine comments and wine prices.

These list API methods share a common structure, taking at least these two parameters: page, count.

All endpoints return objects in reverse chronological order.

  • page : the requested page (ex: 1 for the first page).
    Default value: 1.
  • count : the quantity of items per page (ex: 10).
    Default value: 30

Example request​

$ curl --request GET --url 'https://app.winesitting.com/v1/bottles?page=2&count=50' \
       --header 'AccessKey: YourAccessKey' \
       --header 'SecretKey: YourSecretKey' \
       --header 'content-type: application/json'

Versioning​

When we make backwards-incompatible changes to the API, we release new, annotated versions. The current version is v1. Read our API upgrades guide to see our API changelog and to learn more about backwards compatibility.

All requests need to have version in their URL. The changelog lists every available version.

What do you have to know about "bottles"​

Bottles are the association of 3 elements :

  1. A format (the container : 0.75l, 0.33l...)
  2. A wine (the content)
  3. A user (the owner)

In many systems (maybe yours), the product reference (sku) is different for the same wine in different format. In order to match our "wine/format" with your "product", you have 2 options :