Creating API

Hacks can provide new API applications or extend existing ones with new functions. Overwriting existing functions in applications is not supported.

Prepare file with API

Files with API functions are located in the modules folder. For each "application" for the API, its own file is created. All application functions are placed in one file.

The file name must start with api followed by the application name separated by a hyphen, for example: api-proxy.php. The app name can only contain small latin characters and numbers. The application name can start with either a letter or a number. It is forbidden to use capital letters and symbols, including hyphenes and underscores.

Features of creating functions

All functions responsible for the operation of the API must have a special name: api_app_func, where app is the name application, and func is the name of the function. The function name is subject to the same requirements as the application name.

The function access address is formed from the keyword api, the name of the application and the name of the function itself. The dot indicates the format of the result. For example, a function might be called api_proxy_check, in which case it would be available at api/proxy/check.json.

Important! You cannot create functions with the names of existing system functions. Rewriting system API functions is not available.

The API function always takes two parameters - the core and the ID of the user who called the function. The function must return an array with the results of execution. It is recommended to use the status field in the array, which takes the value error in case of an error and ok in case of success. The error code is usually given in the error field.

An example of a function design:

function api_proxy_check( $core, $user ) {
 $uid = (int) $core->get['uid'];
 if ( $$core->hack->proxyland->check( $uid ) ) {
   return [ 'status' => 'ok', 'id' => $uid ];
 } else return [ 'status' => 'error', 'error' => 'failed' ];
}

The $user parameter is passed to the function even if it has disabled authorization. It is recommended that you always enable authorization for functions.

Connecting functions to the system

ПAPI applications are connected to the system via the api key of the hack initialization array. The value is an array of strings with application names. If your file is called app-proxy.php then the value in the array is proxy.

For example, the proxy application connects like this:

'api' => [ 'proxy' ],

It is recommended that you enable authorization for all API functions you create. The api-auth key in the hack initialization array is responsible for authorization. Each application uses its own array. The first element is the name of the application. The second element specifies an array of strings with function names. If there is only one function, you can specify it as a string instead of an array.

For example, this will require authorization for the check and add functions of the proxy application and the getproxy function of the wm application:

'api-auth' => [
  [ 'proxy', [ 'check', 'add' ] ],
  [ 'wm', 'getproxy' ],
],

Let's look at a complete example of connecting the API in the start.php file. We include a new proxy application that contains the functions check, add, del, edit and list. We are also adding a new getproxy function to the wm system application. All functions require authorization.

return [
  /* … here go the settings of other elements … */
  'api' => [ 'proxy', 'wm' ],
  'api-auth' => [
    [ 'proxy', [ 'check', 'add', 'del', 'edit', 'list' ] ],
    [ 'wm', 'getproxy' ],
  ],
];