REST API Documentation

Introduction

IPS4 provides an extensive REST API to provide a way to consume and create data for third-party applications and websites. Examples of things you can do include creating new topics, registering new members, updating member information, creating Commerce orders and much more besides.

Each IPS4 community provides its own instance of the API. This means that if you're building an app that community administrators can enable in their community, each community needs to create an API key for your integration to use, and REST requests are sent directly to that community - and not to a central API location operated by us.

Authorization

All requests to the API must be authorized by including a valid API key. The community administrator can configure which API keys have permission to access which endpoints, and so naturally your key will also need the relevant permissions to use the endpoints you want to call.

The way to authorize your request depends on the server on which the community is running. The recommended approach is HTTP Basic Auth. Send your API key as the username, with no password.

Alternatively, authorize your requests by sending your API key as the key parameter. For example:

http://www.example.com/api/core/hello?key={apiKeyHere}

Parameters

For all GET requests, provide parameters in the query string. For PUT and POST requests, all parameters should be sent Form URL Encoded in the body.

Response

Responses from the API are always JSON-encoded.

Error Handling

When an error is encountered, you will receive a response like this:

{
	"errorCode": "3S290\/7",
	"errorMessage": "INVALID_API_KEY"
}

The possible error codes/messages for each endpoint are detailed within this documentation reference. In addition to the endpoint-specific errors, the following global errors may also be returned:

Code Message Description
1S290/A IP_ADDRESS_BANNED The IP address that is sending the request has been banned from the community.
1S290/A TOO_MANY_REQUESTS_WITH_BAD_KEY The IP address that is sending the request has sent multiple requests with an invalid API key and so is prevented from sending any more requests for several minutes.
2S290/6 NO_API_KEY No API key was sent in the request.
2S290/8 IP_ADDRESS_NOT_ALLOWED The API key was valid, but is configured to only be valid for requests coming from certain IP addresses and IP address the request was sent from is not in the allowed list.
2S290/B CANNOT_USE_KEY_AS_URL_PARAM The API key was valid, but it is not configured to be used as URL authentication and must be used in AUTHORIZATION headers.
3S290/7 INVALID_API_KEY The API key sent in the request is not valid.
2S290/9 INVALID_LANGUAGE An X-IPS-Language header was sent in the request (which can be used to specify a language ID for the response), but its value was not valid.
3S290/3 INVALID_APP The endpoint the request was sent to does not exist (the first level contains an invalid character, only alphanumerics are acceptable).
3S290/4 INVALID_CONTROLLER The endpoint the request was sent to does not exist (the second level contains an invalid character, only alphanumerics are acceptable).
2S290/1 INVALID_APP The endpoint the request was sent to does not exist (the first level does not exist).
1S290/2 APP_DISABLED The application which controls the endpoint the request was sent to is currently disabled.
2S290/5 INVALID_CONTROLLER The endpoint the request was sent to does not exist (the second level does not exist).
2S291/1 NO_ENDPOINT The endpoint the request was sent to does not exist (the URL contains too many levels).
2S291/3 NO_PERMISSION The API key does not have permission to access the requested endpoint.
3S291/2 BAD_METHOD The endpoint the request was sent to does not exist - the HTTP request method may be incorrect (for example, sending a GET rather than a POST).

Sample Code

Here is a simple code snippet showing a call to the /core/hello endpoint.

<?php
$communityUrl = 'http://localhost:8888/ips4/';
$apiKey = 'c7a349a1629f02cd2855a58d77646f6d';
	
$curl = curl_init( $communityUrl . 'api/core/hello' );
curl_setopt_array( $curl, array(
	CURLOPT_RETURNTRANSFER	=> TRUE,
	CURLOPT_HTTPAUTH	=> CURLAUTH_BASIC,
	CURLOPT_USERPWD		=> "{$apiKey}:"
) );
$response = curl_exec( $curl );

echo $response;
A successful response will look like this:
{
"communityName": "IPS Community Suite",
"communityUrl": "http:\/\/localhost:8888\/ips4\/",
"ipsVersion": "4.1.6"
}