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:
- Acquiring an authentication token (access key) by specifying in your request the ids of the apps whose APIs need to be accessed.
- 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'
tohttp://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