Conventions

Errors

HTTP statuses

If everything is ok, the response is returned with an HTTP status 200.

In case of errors, the following HTTP statuses can be used:

Structure

The following represents a common error response resulting from a failed API request:

{
  "error": {
    "status": 400, // the HTTP status.
    "code": "11003", // WonderPush error code.
    "message": "The provided access token is invalid" // human friendly error description.

  }
}

Reference

Here are the various errors that can be returned by WonderPush, presented here ordered by code:

Pretty printing

For all endpoints returning JSON response you can append ?pretty=true to your requests to pretty print the result (use it for debugging purpose only).

Pagination

Some endpoints return multiple items at once. In that case, when relevant pagination.previous and pagination.next cursors URLs are returned in the response. You can use these cursors to navigate in both directions throughout the result items. A count parameter is also exposed to define how much items to return.
Note that these cursors are only valid for around 2 minutes, so they are only suited for iterating through a large set of results programmatically.

See more information and sample code.

Partial response

If you don’t need the whole content of the response, some endpoints allow specifying a set of fields to return by setting the fields parameter. The fields parameter is given as a comma separated list of field names.

Booleans

All REST APIs parameters support providing boolean false as the values: 0, false, f, n, no, false and true as the values: 1, true, t, y, yes.

Dates and times

WonderPush exclusively uses UNIX timestamps in milliseconds (time elapsed since January 1st 1970), and expresses textual dates and times in UTC, always specifying the used timezone to avoid confusion.

You can also use a textual representation of a date using the following ISO8601 format: YYYY[-MM[-DD]][T[HH[:MM[:SS[.SSS]]]][Z|+HH[:MM[:SS[.SSS]]]]]
Here are valid examples: 2015, 2015-12, 2015-12-31, 2015-12-31T23, 2015-12-31T23:59, 2015-12-31T23:59:59, 2015-12-31T23:59:59.999.
Here are valid offsets you can also append: Z for UTC, -06, +02:00. In the absence of an offset, the date is taken as UTC. Don't forget to write T before the offset if you gave no time-part.
Unless explicitly mentioned, any missing part is taken as January 1st for date-part and midnight for the time-part.

Most API call arguments should also accept a relative date, always relative to the current time, using the following ISO8601 duration format: [+]P[nY][nM][nD][T[nH][nM][nS]] where each n represents a non-negative number.
Here are valid examples: P1Y2M3DT4H5M6S meaning 1 year 2 months 3 days 4 hours 5 minutes and 6 seconds, P1M meaning 1 month (note that there is no T before the M so it refers to months), PT5M meaning 5 minutes (note T ending the date part and starting the time part, so the M refers to minutes), P7D meaning 7 days.
You can prefix the P with an optional + sign. Such relative dates are added to the current time, hence representing a date in the future. PT5M and +PT5M represent both the date in 5 minutes.
You can prefix the P with a - sign. Such relative dates are subtracted to the current time, hence representing a date in the past. -PT5M represents the date 5 minutes ago.
For instance you can list the installations created in the last week by using GET /v1/installations?creationDateFrom=-P7D.
Unlike arguments accepting durations, a date field accepting a relative date is always relative to the time the call is made.

Any field or parameter that ends with Date expects a UNIX timestamp in millisecond as an integer, an ISO8601 formatted string, or (for most of them currently) a date interval relative to the current time.

Durations

WonderPush exclusively expresses durations in milliseconds.
But sometimes milliseconds are not really handy for human inputs. For convenience, WonderPush let’s you express duration as a human readable string comprised of an integer value followed by a unit (optionally separated by a space).
Here is a list of the units you can use:

• Milliseconds: ms, millisecond, milliseconds (the default unit)
• Seconds: s, sec, second, seconds
• Minutes: m, min, minute, minutes
• Hours: h, hr, hour, hours
• Days: d, day, days
• Weeks: w, week, weeks

Here are valid examples: 5s, 120 sec, 15 minutes, 36 hours, 3 day, 4 weeks.

Any field or parameter that ends with Time expects a duration expressed in milliseconds as an integer, or a string with a number and unit.

Limits

The maximum length of all the request headers is no higher than 16 KB, including the request line which contains the HTTP method, URL, query string and HTTP version.
The maximum length of the request body is 10 MB.