Control panel ⇒ Components ⇒ InstantCMS JSON API

The component provides an easy API between the site and a third-party service, for example, a mobile application. The component can log errors and successful requests and display them in a diagram on the main page of the Control panel. Basically, the request syntax and response format is very similar to the Vkontakte official API. This has been done on purpose to simplify integrators’ understanding. API responses are returned in the JSON format only.

Log error requests

Enables logging of bad requests

Log successful requests

Enables logging of successful requests. Attention! Each request to API will be logged.

For each request type it logs:

• key id;
• API method name;
• Error code if there is one;
• Request date;
• Request processing time

All requests to API are signed by an access key that is created in the component admin panel. This is enough for reading requests. You can pass the API key both in the POST/GET parameter and in the request header with theapi_key name. The key length must not exceed 32 symbols. The key is generated automatically, however, you can edit it manually. You can limit each key to an IP address, temporarily disable.

Other methods of authorization and request signing, as well as user authorization methods are being developed

To request any API method (except for the execute method, read about it below), you need to execute the POST or GET request like this:

http://you_instantcms.site.ru/api/method/METHOD_NAME?PARAMETERS&api_key=API_KEY

It consists of several parts:

• METHOD_NAME (required ) — API method name which you would like to send a request to. A full list of methods is available on this page.
• PARAMETERS (optional) — incoming parameters of the corresponding API method, a sequence of the name=value pairs separated by an ampersand. The list of parameters is found on the method description page. Parameter values should be in UTF-8 encoding.
• API_KEY — access key.

Parameters can be passed both by the GET and POST methods. Use POST if you you are going to pass large data (more than 2 kilobytes).

The METHOD_NAME format consists of the controller name, action name and action parameters and it is basically similar to the basic InstantCMS routing. The controller, action and parameters are separated by the «.» (dot) symbol. For example, there is a METHOD_NAME that is called content.get_datasets.articles:

• content - controller (component) name;
• get_datasets - controller action;
• articles - first parameter of this action.

For example, let’s call the content.get_datasets.articles method to get a list of all datasets of the articles content type and in the parameter we’ll specify a need to return all the datasets including hidden ones:

http://you_instantcms.site.ru/api/method/content.get_datasets.articles?api_key=API_KEY&show_all=1

You will get a response in the JSON format (a part of the response has been hidden to avoid cluttering):

{  
   "response":{  
      "count":5,
      "items":{  
         "all":{  
            "id":"1",
            "ctype_id":"5",
            "name":"all",
            “title”:”All",
            "description":null,
            "ordering":"1",
            "is_visible":"1",
            "filters":[  ],
            "sorting":[  ],
            "index":"date_pub",
            "groups_view":[  ],
            "groups_hide":[  ],
            "seo_keys":null,
            "seo_desc":null
         },
         "reviews":{  },
         "translations":{  },
         "featured":{  },
         "rating":{  }
      }
   }
}

Pay attention that all responses are returned in the JSON format only.

The component also provides a Universal Method that allows to launch a sequence of other methods saving intermediate results and returning all of them in one response. Attention! The request will have another basic view:

http://you_instantcms.site.ru/api/execute?PARAMETERS&api_key=API_KEY

Responses that return a paginated list of something include the paging object that contains cells:

• has_next (true or false) - next page availability flag;
• page - current page number;
• per_page - number of elements per page.

They return HTTP CODE 200 to all requests to the methods you_instantcms.site.ru/api/method/ and you_instantcms.site.ru/api/execute/, including error requests. Errors are generated in the JSON response in a special way:

{  
   "error":{  
      "error_code":101,
      “error_msg”:”Invalid access key ",
      "request_params":[  ]
   }
}

Error codes (error_code) mainly coinside with the Vkontakte error codes. In the error_msg cell there is a textual representation in a selected language. Some error messages contain the request_params nonempty field with the parameter names array and their validation errors.

View full API method list

It is quite simple to develop API methods for your components. The whole process of method development comes down to creation of a special action or a hook, at your choice.

The InstantCMS API component supports only External Actions of a controller. For example, we would like to create an action for the youcontroller.list_items API method that will return a list of certain entries. The action name generation mechanism is the following:

api_youcontroller_list_items

The action file’s name will correspondingly be:

api_youcontroller_list_items.php

And will be located at /system/controllers/youcontroller/actions/api_youcontroller_list_items.php.

The action code is created in a standard way but with certain necessary properties:

api_youcontroller_list_items.php

class actionYoucontrollerApiYoucontrollerListItems extends cmsAction {
 
    /**
     * Blocking of direct action calling
     * necessary property
     * @var boolean
     */
    public $lock_explicit_call = true;
    /**
     * Request result
     * necessary property
     * @var array
     */
    public $result;
    /**
     * An array of cell names
     * that should be deleted from the output array
     * optional property
     * @var array
     */
    public $unset_fields;
    /**
     * A flag obliging to check the sig request parameter
     * sig is bound to the site domain and a visitor IP address
     * @var boolean
     */
    public $check_sig = false;
    /**
     * Possible request parameters
     * with validation rules
     * If a request has parameters, you should describe them here
     * The parameter validation rules are set by analogy with the form fields.
     * @var array
     */
    public $request_params = array();
    /**
     * Optional request verification method
     * Certain validation actions are performed in it
     * returns either false in case of successful verification,
     * or the error data array 
     */
    public function validateApiRequest() { return false; }
    /**
     * Basic action performance method
     * Its task is to fill in the $this->result property
     */
    public function run(){
        $this->result = array('items' => array());
    }
 
}

This version differs only by file location and class naming. Taking into account the example above, the hook file should be located at:

/system/controllers/youcontroller/hooks/api_youcontroller_list_items.php

While the class is called:

class onYoucontrollerApiYoucontrollerListItems extends cmsAction {}

Back to Components