NiftyImages REST API

With the NiftyImages API you can query widget/user/image stats enabling an automated way for you to sync data or pass on impression costs to your widget users.

The API is entirely HTTP-based

Methods to retrieve data require a GET request. Methods that create or update data require a POST or PUT request. A DELETE request is also accepted for methods that destroy data. API Methods that require a particular HTTP method will return an error if you do not make your request with the correct one.

HTTP Response Codes are meaningful:

200 OK : The call was successful
201 Created : The resource was successfully created
400 Bad Request : The request was invalid. Examine the message body for details.
401 Unauthorized : The API Key was missing or invalid
404 Not Found : The resource you are trying to GET, UPDATE or DELETE was not found. Examine the message body for details.
500 Internal Server Error : An unhandled exception occured on the server. Please wait and try your request again.

JSON

The NiftyImages API only supports JSON. So instead of XML, HTTP POST parameters, or other serialization formats, all POST or PUT requests required a valid JSON object for the body. Every API call response includes headers and an optional JSON-formatted body.

The resource references and documentation will provide response details about the call, but the following example shows the type of JSON-formatted response to expect from the Widgets endpoint:

[
  {
    "Name": "CKEditor Widget",
    "WidgetKey": "153607b3-da74-48ed-a579-d2d2430a7578"
  },
  {
    "Name": "TinyMCE Widget",
    "WidgetKey": "729c4159-2837-4817-b1d4-104a7ee279b3"
  },
  {
    "Name": "Internal Widget",
    "WidgetKey": "61e1b493-0c56-479f-bc15-259e26e94fcc"
  }
]

Date Format

All dates will be formatted using ISO 8601 (e.g. 2016-03-12T12:00Z). JSON properties will be formatted that way and we will expect All QueryString Parameters to be formatted that way also.

Example Response Body:

{
    "Name": "My First Widget",
    "CreateDate": "2016-02-10T11:23Z"
}

Example Request Variable:

GET https://api.niftyimages.com/v1/Widgets/WIDGET_KEY?startDate=2016-02-10T08:00Z&endDate=2016-03-10T08:00Z HTTP/1.1

Authentication

A valid API Key is required for every request. There are three different ways you can pass in the API Key, use whichever is easiest for your environment. While the rest of the documentation samples use option 1 below, each method will work the same.

1 HTTP Header

Below is an example of putting the API Key inside the HTTP Header of the request.

GET https://api.niftyimages.com/v1/Widgets HTTP/1.1
ApiKey: YOUR_API_KEY

2 Query String

Below is an example of putting the API Key inside the HTTP Header of the request.

GET https://api.niftyimages.com/v1/Widgets?ApiKey=YOUR_API_KEY HTTP/1.1

3 Basic Authentication

Below is an example of using HTTP Basic Authentication to authenticate requests. The username field can be any dummy value, and the password should be the API Key. Given a username "hope" and an API Key "67c27802-f234-4196-b44c-460245d4978e" you would Base64 encode "hope:67c27802-f234-4196-b44c-460245d4978e" resulting in the value aG9wZTo2N2MyNzgwMi1mMjM0LTQxOTYtYjQ0Yy00NjAyNDVkNDk3OGU=.

GET https://api.niftyimages.com/v1/Widgets HTTP/1.1
Authorization: Basic aG9wZTo2N2MyNzgwMi1mMjM0LTQxOTYtYjQ0Yy00NjAyNDVkNDk3OGU=