API calls are handled as HTTPS requests (mostly GET) returning JSON response objects. Note that sending JSON data in the body of a POST request is not supported.
Forming a Call
Along with the API authentication details, you need to know the controller and method you want to call, along with what parameters you want to pass. The most basic example is retrieving a list of all offers via the findAll method in the Offer controller (Offer::findAll). The call to do this looks like:
https://NETWORKID.api.hasoffers.com/Apiv3/json?
Breaking the URL down:
- Base URL: https://NETWORKID.api.hasoffers.com/Apiv3/json?
- API Key: NetworkToken=APIKEY
- Controller: Target=Offer
- Method: Method=findAll
Replace "NETWORKID" and "APIKEY" with your values. You can test your API access with this call, as it doesn't make any changes to data in your network.
Change as of January 2017: If you've used our API prior to January 2017, you'll notice a difference here. The older method (using NetworkID=NETWORKID in the query string) is still valid for the current version of our API, but is deprecated and not guaranteed to work on future revisions.
Adding Parameters
Nearly all methods have parameters. Most "find" methods (including Offer::findAll) have parameters for specifying what fields to return and what values to filter for or sort by. To give a quick example, if you want to return just the offer ID and name for all offers with a status of active, sorted by expiration date descending, form the call like so:
https://NETWORKID.api.hasoffers.com/Apiv3/json?NetworkToken=APIKEY
EXPLORE THIS CALL IN OUR API CALL BUILDER
Refer to the method's documentation for the list of parameters and expected values. For more on using filtering, see our Filtering, Sorting & Paging article. Also, see the Network API index for the full list of controllers, then read through the relevant controllers to find their methods.
Passing in Null Values: To pass a null value in a nullable parameter, include the parameter name and assign nothing to it, such as "¶meter=". Make sure the code you generate includes all the parameters you want to use, including those with null values.
Parsing the Response
The HTTPS response to a call is a JSON object containing two objects: request and response. The data you passed in the request is returned to you in the request object and the result of the call in the response object. Here's a shortened example of the previous call:
{
"request": {
"Target": "Offer",
"Format": "json",
"Service": "HasOffers",
"Version": "2",
"NetworkId": "NETWORKID",
"NetworkToken": "NET2Nk16TYOEYgnJzjgtAWUMAOVxnN",
"Method": "findAll",
"fields": [
"name",
"id"
],
"filters": {
"status": "active"
},
"sort": {
"expiration_date": "desc"
},
"_": "1486761379288"
},
"response": {
"status": 1,
"httpStatus": 200,
"data": {
"8": {
"Offer": {
"id": "8",
"name": "Mobile Mogul (iOS, Free, US, 65MB)"
}
},
"6": {
"Offer": {
"id": "6",
"name": "Atomic Tilt (iPhone, Free, CA, 25MB)"
}
},
"14": {
"Offer": {
"id": "14",
"name": "Fitness Buddy (Android/Tier1/40MB)"
}
},
"12": {
"Offer": {
"id": "12",
"name": "Mondo Burger Sweeps"
}
},
"4": {
"Offer": {
"id": "4",
"name": "Quantum Pirates (Free, Android, Tier3, 35MB)"
}
},
},
"errors": [],
"errorMessage": null
}
}The contents of any results returned are in data. Any errors are listed in errorMessage, with more detail potentially in errors.
Sample Calls
See our Sample Network API Calls article for examples involving frequently used methods and parameters.
Using Our API Call Builder
The documentation for each method includes an API call builder for you to compose and execute API calls.
Important: Any API calls you make in the builder are actually executed on your network, including ones that change data.
On null values: Our API call builder doesn't generate code for any form fields that are empty; empty fields are treated as fields you don't want to use. To render code for null values, use "(NULL)" without quotes as the field's value.
Important Note on Rate Limits
Networks are limited to a maximum of 50 API calls every 10 seconds. If you exceed the rate limit, your API call returns the following error: "API usage exceeded rate limit. Configured: 50/10s window; Your usage: " followed by the number of API calls you've attempted in that 10-second window.
If you occasionally experience rate limit issues, check for that error response, then pause executing API calls for a few seconds before retrying. If you consistently require a higher limit, contact your account manager to have your limit raised, and they can discuss rate limit plans with you.
Continuing From Here
The Network API Setup & Essentials pages cover core topics on using our API, including the common field/parameter types and how to handle filtering, sorting, and paging.
The Network API In Action pages covers different use cases and more specific knowledge. We recommend going over the list of sample API calls in that section.
The Network API Index explains each controller and model in brief.
You can find all of these pages on the sidebar to the left, and use the search feature above that navigation to quickly find pages, controllers, models, and methods based on the name. For example, typing "find" in that box will show you all of the find* methods in every controller.