Jump to content

Community

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

There are two ways to authenticate requests to the REST API: using an API key (all versions), or using OAuth (4.3 and above).

When using an API key, all data is available and all actions can be performed. For example, if you send an API request to GET /forums/topics, every topic in the community will be in the results; if you send an API request to POST /forums/topics you can create a topic as any user on the community. It is therefore very important that you always keep the API Keys secret, and only grant access to the endpoints you intend to use.

Unlike with API keys, when accessing the REST API with OAuth, you will be providing an access token which has been granted to a specific user* and only data that user can see, and actions that user can perform are available. For example, if you send an API request to GET /forums/topics, only topics in forums that the authenticated user can see will be in the results; if you send an API request to POST /forums/topics the topic will be created as the authenticated user and that cannot be changed.

Some endpoints are only available when using one method or the other. For example, GET /core/me gets information about the authenticated user and so can only be used when authenticated with OAuth. Meanwhile, POST /forums/forums creates a forum, which is exclusively a site-level operation and so can only be used when authenticated with an API Key*. Some endpoints, while available to both methods, might accept different request parameters or have different response parameters for different methods which will be explained in the documentation.

* If you are familiar with OAuth and prefer using it for authentication to API Keys, you can also authenticate with Client Credentials which will work similarly to using an API Key, giving full access to the API rather than as a specific user.

Using an API Key (Easy)

The community administrator can generate API keys in AdminCP → System → REST & OAuth → API Keys. Each API Key will need to be configured to which endpoints it can access.

The way to provide the API key in 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. For example:

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

If PHP is running as a CGI module (which can be confirmed by checking the phpinfo output for your server), then you will need to authorize your requests by sending your API key as the key parameter in the request. For example:

<?php
$communityUrl = 'https://www.example.com/ips4/';
$apiKey = 'c7a349a1629f02cd2855a58d77646f6d';
$endpoint = '/core/hello';
	
$curl = curl_init( $communityUrl . 'api' . $endpoint . '?key=' . $apiKey );
curl_setopt_array( $curl, array(
	CURLOPT_RETURNTRANSFER	=> TRUE,
) );
$response = curl_exec( $curl );

Using OAuth (Advanced)

You will need to be familiar with the basic concepts OAuth before you begin. A good resource is OAuth 2 Simplified. The community administrator can create OAuth clients in AdminCP → System → REST & OAuth → OAuth Clients.

Just like with API Keys, the client will need to be configured to which endpoints it can access, however with OAuth, the different endpoints are tied to scopes. For example, you might set up one scope which allows access to the GET /core/me endpoint to get basic information about the authenticated user, and a separate scope which allows access to the POST /forums/topics which allows topics to be posted. The scopes you set up and which endpoints they can access will depend on how you intend the API.

You then will obtain an access token using whichever OAuth grant type you want (usually with an authorization code grant involving redirecting the user) and send that in requests in the Authorization header. For example:

<?php
$communityUrl = 'https://www.example.com/ips4/';
$accessToken = 'c7a349a1629f02cd2855a58d77646f6d';
$endpoint = '/core/hello';
	
$curl = curl_init( $communityUrl . 'api' . $endpoint );
curl_setopt_array( $curl, array(
	CURLOPT_RETURNTRANSFER	=> TRUE,
	CURLOPT_HTTPHEADER	=> array( "Authorization: Bearer {$accessToken}" ),
) );
$response = curl_exec( $curl );

In Invision Community OAuth clients Client Identifiers are 32 characters long, Client Secrets are 48 characters long, Authorization Codes are 64 characters long, and Access Tokens are 97 characters long.

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 or 1S290/C IP_ADDRESS_BANNED The IP address that is sending the request has been banned from the community. This may happen automatically if the IP Address has repeatedly sent many requests with invalid API keys.
1S290/D 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 or OAuth access token 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).
3S290/9 INVALID_ACCESS_TOKEN The OAuth access token sent in the request is not valid.
1S290/E EXPIRED_ACCESS_TOKEN The OAuth access token sent in the request was valid but has expired.
3S290/B NO_SCOPES The OAuth access token has not been authorised to access any scopes.

Sample Code

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

<?php
$communityUrl = 'http://www.example.com/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"
}
×