Help: 1. API Basics

Help Portal » Knowledgebase » WhisperGifts API » 1. API Basics

Basic details about accessing the WhisperGifts API, including authentication, terms of use, possible uses, available data sets, and how the consistent resource URL addressing works.

The WhisperGifts API allows third party applications to perform some actions on behalf of an active WhisperGifts user. Visible data includes items and RSVPs, plus some supporting read-only data (such as item categories).

The WhisperGifts API is only available to users who have a paid package. API access is not available to free users.

Important: The WhisperGifts API is currently in public beta and should be considered "version zero". Functionality is somewhat limited, and we are still looking for suggestions as to what else should be made available or how else you might want to use the API. I encourage you to build a business idea on top of this API, but please be careful!

Authentication

If you have a currently logged-in browser session, you can perform GET requests for every resource type (including lists and detail views) and your current session will provide sufficient authentication.

For more advanced use you will need to authenticate using your API key. This needs to be provided as an additional header in your HTTP request, called API-Auth. Username and password authentication is not provided.

The API-Auth header is made up of two components, the user ID and the user API key, joined by a colon (":"). The user ID is static for a given registry and will never chnage; the API key can be refreshed by the user at any time and without any notice. API keys are 32 alphanumeric characters, taken from the range [0-9a-z].

A sample API-Auth header is included below for user ID 4284, with the API key beginning with 0kgae....

API-Auth: 4284:0kgae6zycxywmp8d38pfvjq6m8hokof0

Your API key can be found by visiting your WhisperGifts management page and clicking "API". The API key for your account can also be reset here, in case it is lost or accidentally shared.

Possible Uses

You might use the WhisperGifts API to build new types of applications that enhance the use of WhisperGifts. Examples include mobile phone apps, integration with shopping cards on external websites, automated gift creation and tracking, and more.

Terms of Use

In addition to the WhisperGifts Terms of Use, the following rules also apply to all use of the API.

  1. Rate limits may be applied.
  2. Third party applications may not request or store a users login username or password. API keys may be stored securely.
  3. Any website collecting WhisperGifts API keys must use https encryption on any page that collects or displays that API key
  4. You may not perform malicious actions on a users' account
  5. You may only perform actions using an API given to you in good faith, and only for the purpose in which the user provided their API key.
  6. If you store API keys, a user must be able to request deletion of those keys without human involvement from your side. Deletion must be instant and permanent; all use of the API key must cease instantly.
  7. You may charge for your use of the API, but you must direct the user to sign up for a WhisperGifts themselves and pay any account fees directly to WhisperGifts (ie: You cannot signup a user and charge them yourself, and create a WhisperGifts account in the process).
  8. API access may be withdrawn at any time for any reason

Requests / Responses

Requests follow a basic pattern. All resources have a static and predictable URL, and standard HTTP methods and response codes are utilised to perform different actions.

Request Type URI Method HTTP Request Body HTTP Response
List of [resource] objects /api/v0/[resource]/ GET   JSON List
Create a single [resource] /api/v0/[resource]/ POST JSON object representing a single [resource] JSON object representing created object (including generated id)
Get a single [resource] /api/v0/[resource]/[id]/ GET   JSON object representing a single object, as identified by [id]
Update a [resource] /api/v0/[resource]/[id]/ PUT JSON Object representing [resource] JSON object representing updated object
Delete a [resource] /api/v0/[resource]/[id]/ DELETE    

All successful requests will respond with a HTTP 200 code, and a JSON body if appropriate. Errors will include HTTP 404 (object not found), HTTP 403 (access denied), and HTTP 405 (method denied).

Where a request contains a body, it will be in JSON format and may include UTF-8 characters. Any response that includes a list of items (such as the category list or item list) wraps all objects in an objects object.

All list-type responses are also paginated when there are greater than 50 items; you should read the num_pages and page items in the JSON response to determine whether there are more items to be shown. You can request a particular page with a page parameter; you may override the number of items per page by passing in a per_page parameter (maximum of 500 items returned per page)

All data that you POST or PUT via your HTTP request body (for example, when creating or editing a record) must also be in JSON format.

Resource Types

Resource List Detail Update Delete Documentation Notes
Categories
/api/v0/categories/
    Category API Category data is read-only. A category is mandatory on every item. This endpoint gives you a list of current categories. This list is relatively static, but is subject to change. Names should always be shown to users, however IDs should be used in your JSON requests.
Items
/api/v0/items/
Item API User will have full read/write/update/delete permissions to items on their own registry. Items for any other registry are not visible, let alone able to be modified.
RSVPs
/api/v0/rsvp/
RSVP API User will have full read/write/update/delete permissions to RSVPs for their own wedding. Responses for any other registry are not visible, let alone able to be modified.
Account
/api/v0/account/
      Account API Read-only access to details about the users registry, including hostname and wedding date.