API

Contents...

Access to the API of the Webasyst framework and all installed Webasyst apps is performed via api.php access point.

Authentication is based in the OAuth 2.0 protocol:

  1. Acquiring an authentication token (access key) by specifying in your request the ids of the apps whose APIs need to be accessed.
  2. Use the acquired token to call API methods of the specified apps. When API methods are called access rights of the authorized user are taken into account.

Below is a detailed description of these two basic steps.

1. Acquiring a token (access key)

A slightly modified and simplified version of the OAuth 2.0 protocol is used: http://oauth.net/2/.

A request for a token redirects a user to the website where the Webasyst framework is installed for the user to authenticate by entering a login name and a password (it is essential that authorization data are entered by user on the website with installed Webasyst framework and not within the client applications which attempts to acquire a token). Upon authorization, user accepts or declines access to the API.

Example of a token: b936356100e3883cabf59abed991d03d.

Token life time is not limited.

A token is issued only if access to the API si granted. Below is a description of the application request scheme (excerpt from the OAuth 2.0 protocol documentation):

A. Web Server Applications

Redirect users who wish to authenticate to
http://ACCOUNT_URL/api.php/auth?client_id=CLIENT_ID&client_name=CLIENT_NAME&response_type=code&scope=SCOPE&redirect_uri=REDIRECT_URI&format=FORMAT

If a user accepts, they will be redirected back to
REDIRECT_URL?code=CODE

otherwise to
REDIRECT_URL?error=access_denied

Your server must send a POST request with the following fields

code: CODE,
client_id: CLIENT_ID,
grant_type: 'authorization_code'

to http://ACCOUNT_URL/api.php/token?redirect_uri=REDIRECT_URI&format=FORMAT

The response will be JSON or XML (&format=XML)

{ "access_token" : ACCESS_TOKEN }

or

<response>
    <access_token>ACCESS_TOKEN</access_token>
</response>

B. Client applications

Redirect users who wish to authenticate to
http://ACCOUNT_URL/api.php/auth?client_id=CLIENT_ID&client_name=CLIENT_NAME&response_type=token&scope=SCOPE&redirect_uri=REDIRECT_URI&format=FORMAT

If a user accepts, they will be redirected back to
REDIRECT_URL#access_token=ACCESS_TOKEN
otherwise
REDIRECT_URL#error=access_denied

Legend

ACCOUNT_URL: URL of the Webasyst root directory

CLIENT_ID: unique app id; e.g., XYZCompanyShopImportApp; for web apps a domain should be specified to avoid naming conflicts; app id should be created at developer's discretion

CLIENT_NAME: app name to be displayed in the access request page

SCOPE: apps to which access is being requested, separated with a comma; e.g., scope=shop,photos,blog

REDIRECT_URI: URL to which user will be redirected upon accepting or declining access to apps' data

CODE: one-time code for acquiring a token, valid during 3 minutes

FORMAT: optional parameter specifying the data exchange format: xml or json; if empty, json is used by default

2. API requests

When making requests to API methods, set the value of the Content-Type header to application/x-www-form-urlencoded or multipart/form-data (for cases when file uploading is necessary).

API calls are performed as such:

http://ACCOUNT_URL/api.php/APP_ID.METHOD?PARAMS&access_token=ACCESS_TOKEN&format=FORMAT

For example, http://localhost/api.php/shop.product.getInfo?id=4&access_token=ACCESS_TOKEN&format=xml

Alternative method

http://ACCOUNT_URL/api.php?app=APP_ID&method=METHOD&PARAMS&access_token=ACCESS_TOKEN&format=FORMAT

Secure transfer of an access token

To avoid eventual interception of an access token from the URLs of API requests, use one of the following approaches, which is most appropriate for a specific case:

  • include a token in POST request field access_token and send a request to a URLs without this value; e.g., http://mydomain.com/api.php/shop.product.getInfo?id=4
  • send HTTP header AUTHORIZATION in the format “Bearer ACCESS_TOKEN”.

    Examples

        /**
        * waNet
        */
        
        $net = new waNet([
            'authorization' => true,
            'auth_type' => 'Bearer',
            'auth_key' => '1d1863e4afd0fd818a74adbb56e9c2a6',
            'format' => waNet::FORMAT_JSON,
        ]);
        $response = $net->query('https://mydomain.com/api.php/shop.product.getInfo', [
            'id' => 4,
        ], waNet::METHOD_GET);
        
        /**
        * PHP curl
        */
        
        $curl_h = curl_init('https://mydomain.com/api.php/shop.product.getInfo/?id=4');
        
        curl_setopt($curl_h, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer 1d1863e4afd0fd818a74adbb56e9c2a6',
        ]);
        
        # do not output, but store to variable
        curl_setopt($curl_h, CURLOPT_RETURNTRANSFER, true);
        
        $response = curl_exec($curl_h);
        $response = json_decode($response, true);
        
        /**
        * jQuery
        */
        
        $.ajax({
            url: 'https://mydomain.com/api.php/shop.product.getInfo/?id=4',
            headers: {
                'Authorization': 'Bearer 1d1863e4afd0fd818a74adbb56e9c2a6'
            }
        }).then(function(response) {
            console.log(response);
        });
  • METHOD

    name of method; e.g., shop.category.getTree, stickies.sheet.getList

  • PARAMS

    parameters accepted by method; e.g., parent_id=0&max_level=3

  • ACCESS_TOKEN

    token acquired upon authorization

  • RESPONSE

    optional parameter specifying the data exchange format: xml, json; if empty, json is used by default

  • APP_ID (for alternative method)

    app id; e.g., shop, stickies, photos, blog

  • FORMAT

    optional parameter specifying the data exchange format: xml, json; if empty, json is used by default

In case of an error, the error field becomes available:

JSON

{ "error" : "invalid_request" }

XML

<response>
    <error>invalid_request</error>
</response>

Error codes (error element)

  • invalid_request

    incorrectly formed request; additional information is contained in field error_description

  • access_denied

    this token does not allow access to the specified method

  • invalid_method

    an unknown API method is being called