-
Notifications
You must be signed in to change notification settings - Fork 0
DealNews Private API
The DealNews Private API describes the resources that are available for mobile devices to access and update user content. Please start with the DealNews Public API as all content-related resources are described therein. The only difference being that some of the content is formatted differently for mobile devices.
Note that all API responses for mobile devices return JSON encoded data.
The only HTTP verbs supported are GET and POST. PUT and DELETE are not supported.
The private API authorization is based on the Amazon S3 Authentication model.
An API key and message signature generated from a secret key are required for access to the DealNews Private API. The API and secret keys are provided by DealNews. The message signature is a HMAC (Hash Message Authentication Code) generated from the request string and the secret key. Here are instructions on how to generate request signatures for API calls using the secret key.
The HMAC signature generation requires a timestamp. This timestamp must also be present in the request header as x-dn-date and should consist of a full UTC timestamp, e.g. Wed Feb 29 2012 11:56:35 GMT-0600 (CST).
GET /some/path
Authorization: DN api-key:message-signature-hash
x-dn-date: utc-timestamp
All API calls will have a response status returned in the JSON data. The "status" parameter will be a string with three different values:
Success status indicates that the response performed as expected.
A fatal error occurs when an API-level failure occurs. For example if an invalid key is provided, a "fatal_error" status will be returned. In iOS, this logic happens in the base-level API call queue level, independent of application code.
Along with a status=fatal_error, a "code" parameter will also be provided.
The following shows the fatal_errors and what should be done when the application receives them.
The Content-accept header need not be used. If it is specified, only a value of "application-json" is valid.
This resource is not valid. Please let us know if you are having difficulty locating a resource or if you need this resource to be available.
This is a problem on our end. We have been notified.
These are a problem on your end. (Probably.)
If this ever gets sent to your app, you should throw away the key that was used in this request and request another.
You are not allowed to be here.
You shouldn't get these.
You must provide x-dn-date for those resources that require full authorization + HMAC.
You must provide HMLC for private (e.g., user-related) resources.
If this ever gets sent to your app, you should throw away the key that was used in this request and request another.
We did not get a correct match on the Authorization header's HMAC.
If an API resource fails for any reason, the status will be "error." An example of this would be when an incorrect username and password are supplied to login. If an API call fails for any reason, an error response will be indicated in the JSON response . The error information is provided at the topmost level in the response object.
TBD.
Mobile devices must register with DealNews to receive an API key which will allow access the API. The different mobile apps each include a codebase-specific, generic API key (and shared secret key) which allows API calls to request a device-specific API key and the corresponding shared secret key.
GET /register
Authorization: DN generic-api-key:message-signature-hash
x-dn-date: utc-timestamp
On application uninstall, the device will un-register its device-specific key.
GET /unregister
Authorization: DN api-key:message-signature-hash
x-dn-date: utc-timestamp
The application should call the ping endpoint each time it comes to the forefront with the following time constraint. The app should check the time difference between now() and the last time the application came to the forefront to ensure that ping does not get called too often. Simply cycling from app to mail and then directly back to app should not force an additional ping. Are there any style guidelines on this duration? If not, the minimum time between back to back ping calls should be greater than 5 minutes.
GET /ping
Authorization: DN api-key
Note that the ping endpoint does not require a HMAC in the authorization.
The private API allows a user to log in to their account and modify user settings. On successful login, the API key is associated with the user account until the user logs out.
Attempt to authenticate the user with an email address and password. This request requires the following parameters to be provided in the POST data:
Key | Type | Description :---|:-----|:--------|:----------- email | string | the email address of the account holder password | string | the account password
POST /login
Authorization: DN api-key:message-signature-hash
x-dn-date: utc-timestamp
Content-type: application/x-www-form-urlencoded
email=some%40email.com&password=password
Disassociate the device from the user account.
GET /logout
Authorization: DN api-key:message-signature-hash
x-dn-date: utc-timestamp
Create or edit a user account.
Key | Type | Description :---|:-----|:--------|:----------- name | string | the full name of the account holder email | string | the email address of the account holder password | string | the password to assign to the account
POST /user
Authorization: DN api-key:message-signature-hash
x-dn-date: utc-timestamp
Content-type: application/x-www-form-urlencoded
name=your%20name&email=some%40email.com&password=password
When editing an account, the POST data must include the password and can include any of the following key-value pairs:
Key | Type | Description :---|:-----|:--------|:----------- email | string | email address of the account holder password | string | account password username | string | username associated with the account firstname | string | first name of the account holder lastname | string | last name of the account holder address1 | string | street address address2 | string | secondary street address city | string | city state | string | state postal | string | postal code email_format | string | one of HTML or TEXT
POST /user
Authorization: DN api-key:message-signature-hash
x-dn-date: utc-timestamp
Content-type: application/x-www-form-urlencoded
password=password&...
POST /user
Authorization: DN api-key:message-signature-hash
x-dn-date: utc-timestamp
Retrieve account information. Also retrieves newsletter settings and list of alerts.
GET /user
Authorization: DN api-key:message-signature-hash
x-dn-date: utc-timestamp
Retrieve details for an alert.
GET /user/alert/<alert id>
Authorization: DN api-key:message-signature-hash
x-dn-date: utc-timestamp
Update alert information. POST data must include key-value pairs of the data to be updated. Valid keys are:
Key | Type | Description :---|:-----|:--------|:----------- store_id | integer | the store id to which the alert is associated keywords | string | keywords for the alert category_id | integer | the category id to which the alert is associated send_to_email | integer | if non-zero, alerted deals will be sent to the email address on file send_to_device | integer | if non-zero, alerted deals will be sent to mobile devices associated with the account price_high | float | deals with prices lower than this value will be alerted
POST /user/alert/<alert id>
Authorization: DN api-key:message-signature-hash
x-dn-date: utc-timestamp
Content-type: application/x-www-form-urlencoded
store=1234&keywords=receiver,audio&...
Create a new alert. POST data must include key-value pairs of the new alert data. Valid keys are same as for "Update Alert" above. At a minimum, one of keywords, category_id or store_id must be specified.
POST /user/alert
Authorization: DN api-key:message-signature-hash
x-dn-date: utc-timestamp
Content-type: application/x-www-form-urlencoded
keywords=receiver,audio&...
To remove an alert, the POST data must include a non-zero value for remove_alert.
POST /user/alert/<alert id>
Authorization: DN api-key:message-signature-hash
x-dn-date: utc-timestamp
Content-type: application/x-www-form-urlencoded
remove_alert=1
In order to save a piece of content to a user's account, the following call must be made:
GET /user/save/<content type>/<content type id>
Authorization: DN api-key:message-signature-hash
x-dn-date: utc-timestamp
The content type in the above call can be one of article, coupon, or bfad. The content type id is the unique id of the item to save.
In order to remove a saved piece of content from a user's account, the following call must be made:
GET /user/remove_saved/<content type>/<content type id>
Authorization: DN api-key:message-signature-hash
x-dn-date: utc-timestamp
The content type in the above call can be one of article, coupon, or bfad. The content type id is the unique id of the item to save.
To post a comment to a content item, the following call should be made:
POST /item/<content type>/<content type id>/comments
Authorization: DN api-key:message-signature-hash
x-dn-date: utc-timestamp
Content-type: application/x-www-form-urlencoded
comment=text
Configure a device to receive alerts. This registers a device with the DealNews alert system. The POST data must include the aid key with the devices unique application id as the value. On iOS, this value should be the device token that is provided in the callback method -application:didRegisterForRemoteNotificationsWithDeviceToken:
POST /notify
Authorization: DN api-key:message-signature-hash
x-dn-date: utc-timestamp
Content-type: application/x-www-form-urlencoded
aid=<unique application id>