# Apelează servicii externe cu API() și driverele din NEWAPI()

> Înregistrează un driver pentru un serviciu cu NEWAPI() și apelează-l din acțiuni cu API(name, schema, data), în același stil de callback, eroare și promisiune ca query builder.

Framework: total5
Product: Total.js 5 (total5@0.0.19)
Language: ro
Content-SHA256: fd4bd96b44cd5c21004ecf9e4188f608c2233ab4a1a37f857d295837c79456fb
Snapshot: c0700e321579725c5cf4f5ace1ad7d2866d1b4f93c24a63c0b41b6b7998e976c
Sources: total5-installed@total5@0.0.19
Review: not-recorded

`API(name, schema, data, [$])` apelează o operație a unui serviciu extern, iar `NEWAPI()` înregistrează **driverul** care face apelul, astfel încât codul acțiunilor tale nu depinde de modul în care se ajunge la serviciu (HTTP, o bibliotecă, o coadă...).

- `NEWAPI('name', driver)` înregistrează driverul serviciului `name` (`'a,b'` înregistrează un driver pentru două nume, iar `NEWAPI(driver)` îl înregistrează pe cel `default`). `NEWAPI('name', config, driver)` păstrează și un obiect `config` pe care fiecare apel îl primește ca `options.config`.
- Driverul este `function(options, next)`. `options.name` este serviciul, `options.schema` operația, `options.data` datele, iar `options.config` configurația. Răspunde cu `next(error, response)`.
- `API('name', 'operation', data)` returnează un builder: încheie-l cu `.callback($)` (răspunsul merge la acțiunea `$`), `.callback(function(err, response) {})` sau `await ....promise($)`. `.configure({ key: value })` adaugă la `options.config` pentru acel apel, iar `.error('text')` face ca un răspuns gol să eșueze cu acel mesaj.
- Dacă pentru nume nu este înregistrat niciun driver, apelul eșuează cu `API is not initialized`.

```js definitions/api.js
// The driver of a fake weather service: in a real one this would be an HTTP request
NEWAPI('weather', { unit: 'C' }, function(options, next) {
	if (options.schema === 'forecast')
		next(null, { city: options.data.city, temperature: 21, unit: options.config.unit, service: options.name });
	else
		next('Unknown operation ' + options.schema);
});
```

```js controllers/weather.js
exports.install = function() {
	ROUTE('GET /forecast/', forecast);
	ROUTE('GET /forecast-fahrenheit/', fahrenheit);
	ROUTE('GET /unknown/', unknown);
	ROUTE('GET /missing/', missing);
	ROUTE('GET /promise/', promise);
};

function forecast($) {
	API('weather', 'forecast', { city: $.query.city }).callback($);
}

function fahrenheit($) {
	API('weather', 'forecast', { city: $.query.city }).configure({ unit: 'F' }).callback($);
}

function unknown($) {
	API('weather', 'rain', {}).callback($);
}

function missing($) {
	API('nobody', 'forecast', {}).callback($);
}

async function promise($) {
	const data = await API('weather', 'forecast', { city: 'Oslo' }).promise($);
	$.json({ city: data.city, same: true });
}

```