Accessing the API
The API for a particular installation is always found at <XF url>/api/
. (Note that to ensure consistent URLs, the API always uses the "friendly URL" style.) All routes will be accessed under this URL.
The API key you generated must be passed in via a custom XF-Api-Key
header added to your request.
If you are using a super user key, you may pass the user ID of the effective user via the XF-Api-User
header; if you don't pass any user in, the request will default to acting as a guest.
Further request parameters may be sent via the query string or a application/x-www-form-urlencoded
body. (Note: multipart/form-data
is also supported, but for POST requests only.)
By default, all requests will respect user permissions. Super user keys may bypass this on a request-by-request basis by setting the api_bypass_permissions
parameter to 1.
The API always responds with JSON. Errors will always return a response code in the 400 range. Successful requests will return a 200 code. While not commonly used, redirects will return a 300-range code.
Errors always take a standard form. Here's an example:
[code=json]
{
"errors": [
{
"code": "api_key_not_found",
"message": "API key provided in request was not found.",
"params": []
}
]
}
[/code]
Note that more than one error may be returned (such as if you have multiple errors when creating a thread).
In most cases, the error code is the name of the phrase used by the error. The message itself may change and should not be used for automated processing.
For successful requests, the response data will vary by route, so let's talk more about the routes...