Генерация URL для rest API

Для генерации адреса c целью доступа к API есть специальный метод

SUGAR.App.api.buildURL(
	module, // Строка, имя подуля (Calls,Accounts,Opportunities)
	action, // действие, параметр необязательный,
			// прилепляется в конец итогового URL
	attributes, // необязательный объект,
				// можно задать id записи, link и relatedId
	params // необязательный объект для дополнения адреса get переменными
)

К примеру для привязки существующего звонка к сделке — url должен быть следующего вида
/<module>/:record/link/:link_name/:remote_id
для получения такого результата параметры должны быть следующими

SUGAR.App.api.buildURL(
	'Accounts', // основной модуль
	'', // не нужен в данном случае
	{
		link : 'calls', // связанный модуль
		id : '123-456', // ид сделки (записи основного модуля)
		relatedId : '789-012' // ид звонка (записи связанного модуля)
	}
)

на выходе получаем следующий url:
rest/v10/Accounts/123-456/link/calls/789-012
его уже можно использовать в вызове методов rest API

Для случаев типа /<module>/filter/count — достаточно указать модуль и в качестве action — оставшуюся часть ссылки «filter/count»

SUGAR.App.api.buildURL('Accounts', 'filter/count')

Параметр params этого метода введен, видимо, на всякий случай, совершенно, правда, непонятно на какой.
Этот метод всегда работает в паре с SUGAR.App.api.call, который принимает объект data со всеми данными, которые необходимо передать на сервер, и сам уже решает куда помещать эти данные: в post или в get параметры.

Вызов метода rest API javascript

Вызов метода API бэкэнда осуществляется следующим методом javascript API

SUGAR.App.api.call(method, url, data, callbacks, options)

первый параметр method — это вопреки ожиданиям не HTTP метод, а CRUD action, который может принимать одно из значений:
— read (GET)
— create (POST)
— update (PUT)
— delete (DELETE)
В скобках указан HTTP метод, который придет в бэкенд, именно он должен быть указан в массиве регистрации метода API c ключом «reqType», к примеру для обновления записи (метод js api — «update», метод для PHP rest api — «PUT»)

public function registerApiRest() {
    return array(
        'saveSomething' => array(
	    'reqType' => 'PUT',
	    'path' => array(
                'Opportunities', 
                '?', 
                'save-something'
            ),
            'pathVars' => array(
                'module', 
                'id', 
                'method'
            ),
            'method' => 'saveSomething',
            'shortHelp' => 'save something for opportunity',
            'longHelp' => '...save-something.html',
    ),
    ...

Второй параметр — url
Указывать прямую ссылку — явно дурной тон, будем использовать для этого возможности js api, об этом в следующем посте
Третий параметр — data — привычный объект c данными, которые необходимо передать на сервер, к примеру

{
    summa: 10000,
    sales_stage: "work"
}

Четвертый параметр — callbacks — объект с функциями-коллбэками

{
    success: function(answer) {
        "Успешное завершение вызова, answer (при дефолтных параметрах) - объект";
    },
    error: function(error) {
        "Произошла какая-то ошибка, лучшее решение в этом случае - показать сообщение об ошибке и добавить какие-то рекомендации человеку, который возможно это увидит";
        App.alert.show('wrong_save', {level:'error',autoClose:false,messages:error.message+"\n Попробуйте перезагрузить страницу и попробовать заново, если не поможет - сообщите программисту."});
    },
    complete: function() {
        "Этот коллбэк отработает в любом случае, тут можно убрать блокировки на время загрузки"
    },
}

Ну и последний параметр — это объект с параметрами для совершения ajax запроса
Дефолтные параметры:

{
    url: null, // если url не указали вторым параметром - его можно указать здесь
    type: "GET", // тут можно указать HTTP метод напрямую
    dataType: 'json',
    headers: {},
    timeout: 30000, // 30 sec
    contentType: 'application/json'
}