Composr Tutorial: Server-side public API

URL Structure

The API is split into a number of endpoints, which are given a 'hook' name, and categorised by 'hook type'. Hooks are located under sources[_custom]/hooks/endpoints/<hook-type>.

Both REST-style and GET-parameter style requests can be made. We recommend using the REST-style URLs as they are widely supported and understood. But if you prefer Composr syntax, use the GET-parameter URLs instead.

Here are 2 equivalent example API calls…

• POST http://yourbaseurl/data/endpoint.php?hook_type=somehooktype&hook=somehook&type=edit&id=someid (GET-parameter style)
• PUT http://yourbaseurl/data/endpoint.php/somehooktype/somehook/someid (REST style)
  • Method PUT is mapped to Composr type "edit"
  • The path after endpoint.php follows the structure <hook_type>/<hook>/<id>

Notice these differences:

1. Request method vs simple GET/POST with use of Composr-style type parameter.
   They are mapped as follows (method=type): GET=view, PUT=edit, POST=add, DELETE=delete.
2. The path components after the PHP file, versus use of hook_type, hook, and id GET parameters.

Apart from the standardised type and id request parameters described above, input parameters are usually just put through as GET/POST parameters (i.e. not submitted via POSTed/PUT JSON data). Data can also be streamed to an endpoint (except in GET and HEAD requests) which is then parsed into the endpoint system via php://input as a data POST parameter. This is useful when using file streams to send data or when passing encrypted payloads.

Different endpoints may use different parameters. It is up to the endpoint how to use the parameters, even the meaning of type and id is not defined and those parameters are not required by all endpoints.

Authentication / Authorisation

Endpoints can employ zero or more authorisation types listed below:

• None / false
  No authorisation is necessary to call the endpoint. This is typically used by the endpoints responsible for authorising someone (we usually cannot authorise someone if the authorisation endpoint itself requires authorisation) and for widely public content / functionality.
• member, staff, or super_admin
  The person accessing the endpoint must authorise as one of the indicated members of the site, where member is any member, staff is any staff member (as defined by the forum driver), and super_admin is any super-administrator (as defined by the forum driver).
  Authorisation can be performed one of these ways (if multiple methods are provided at the same time, the one closest to the top of the list will take priority):
  
  • Providing an Authorization header where the value is Basic <base-64 encoded username:password> (the response headers will include a session cookie which you can use in future requests)
  • (Composr Mobile SDK) Providing cookies or POST parameters (device_auth_member_id_cn/device_auth_pass_hashed_cn/device_auth_member_id_vl/device_auth_pass_hashed_vl) generated from the endpoint account/login
  • Providing login cookies in the request
  • Providing a session cookie or a keep_session URL query parameter in the request
• maintenance_password
  The person accessing the endpoint must authorise using the maintenance password of the site. This should be passed as an Authorization header with the value Basic <base-64 encoded maintenance password>. Once authorised, the API endpoint will run on behalf of the first admin user. Note that if the maintenance password has been removed (as we generally recommend when not using maintenance scripts), then these endpoints will always throw access denied.

If an endpoint lists more than one authorisation type, then only one of them have to pass for the endpoint to be available for use.

Additional authorisation types can be developed in sources_custom/hooks/systems/endpoint_authorization. Make sure if your addon utilises any authorisation types belonging to other addons that your addon info lists the other addons as a required dependency.

Responses

JSON is returned in the response as a structure like this:

Any endpoint may return an error as a false success, so the iOS/Android code must handle this. If there is an error, error_details will always be set. Error messages are guaranteed to be human-readable and to be translatable, so you can show them directly to mobile users.

The particular data returned within response_data varies by endpoint.

See also

• Mobile design
• Mobile apps via Composr Mobile SDK

Feedback

Have a suggestion? Report an issue on the tracker.