Le schermate mostrano l’interfaccia in inglese.
API collega Simbioza ad altri sistemi. Un amministratore innanzitutto installa e abilita il modulo API, quindi rilascia una chiave a un utente attivo reale. Una chiave ha ambiti selezionati, scadenza opzionale e restrizioni IP. Si applicano ancora le attuali autorizzazioni utente: un ambito amministrativo non trasforma un utente normale in un amministratore.
La guida dell'amministratore tratta il rilascio, l'approvazione, la rotazione e la revoca delle chiavi. Questo capitolo riguarda l'integrazione delle applicazioni. Ogni comando e risposta visualizzata è stata verificata con richieste HTTP reali e dati sintetici isolati. ID, timestamp e ETag differiranno a seconda dell'installazione; utilizzare i valori restituiti dalle proprie richieste. I segreti vengono sostituiti con [REDACTED].
Preparazione
Imposta l'indirizzo di installazione, inclusa la sua sottodirectory, senza una barra finale. Mantenere la chiave fuori dal codice sorgente e dai repository pubblici.
export BASE_URL='https://example.org/simbioza'
read -r -s SIMBIOZA_API_KEY
export SIMBIOZA_API_KEY
I comandi utilizzano curl --globoff quindi le parentesi nei parametri come page[limit] non vengono interpretate come modelli URL. jq seleziona solo estratti leggibili da risposte di grandi dimensioni; Simbioza non lo richiede. Invia la chiave in Authorization: Bearer, mai nell'URL o in un cookie del browser.
Corpi delle richieste e risposte
Le scritture usano Content-Type: application/json e un oggetto di primo livello con campi denominati. {} è un oggetto valido, anche se un'operazione può richiedere campi specifici. [], i valori scalari e i nomi numerici dei campi di primo livello non sono validi; le liste annidate restano supportate. Un esempio può omettere il corpo quando l'operazione non lo legge. Le modifiche ai sondaggi richiedono JSON e le relative informazioni di versione.
Le risposte JSON riuscite usano data, meta e links. meta.request_id identifica una richiesta nei registri. Una risposta 204 non ha un corpo JSON. OpenAPI restituisce direttamente il documento; allegati ed esportazioni CSV, ICS e ZIP restituiscono file. Controlla Content-Type prima di decodificare JSON.
Impaginazione
Molti elenchi utilizzano page[limit] (predefinito 50, massimo 100) e un opaco page[after]. Segui links.next finché non diventa null; non costruire o modificare i cursori. Un cursore non valido potrebbe restituire la prima pagina. La paginazione è specifica per risorsa: il sondaggio utilizza page/per_page, la ricerca utilizza anche page/per_page e i riepiloghi dell'area di lavoro utilizzano page/limit. Gli elementi seguiti personali restituiscono un elenco limitato senza il contratto del cursore.
Aggiornamenti simultanei
Per i percorsi contrassegnati con If-Match, prima GET la risorsa o bozza corrente e leggere la sua intestazione HTTP ETag. Invia il valore esatto, comprese le virgolette, nell'intestazione If-Match della scrittura successiva. Gli esempi chiamano quella variabile ETAG. Non utilizzare ETag di un'altra lingua o ETag di una pagina pubblicata quando si aggiorna una bozza. Per impostazione predefinita, una precondizione mancante restituisce 428 e una obsoleta 412. Le bozze HTML utilizzano inoltre draft_revision. Survey utilizza i propri version e revision invece degli ETag.
curl --globoff --silent --show-error \
--header "Authorization: Bearer $SIMBIOZA_API_KEY" \
--dump-header response-headers.txt \
"$BASE_URL/api/v1/me"
Ciò dimostra il salvataggio delle intestazioni di risposta. Ottieni ETAG dalla risorsa appropriata GET, non da /me.
Scritture e limiti ripetuti
Le scritture JSON possono utilizzare un Idempotency-Key univoco. La stessa chiave e richiesta riproducono la risposta precedente; riutilizzare la chiave con un corpo diverso restituisce 409. I caricamenti in più parti e binari non supportano questa intestazione e restituiscono 422. Il valore predefinito è 120 richieste al minuto per chiave, con intestazioni X-RateLimit-* e Retry-After su 429; gli amministratori possono configurare un altro limite. Il corpo massimo predefinito di JSON è 2MiB e i singoli moduli applicano limiti aggiuntivi. CORS è un criterio amministrativo separato e non sostituisce l'autenticazione Bearer.
Leggi OpenAPI con una chiave valida. Elenca i percorsi e gli ambiti registrati dai moduli attivi, ma i suoi schemi generici non descrivono completamente i parametri aziendali, i campi multiparte o le risposte binarie. Utilizza anche i capitoli delle risorse. CalDAV e i collegamenti ICS pubblici sono protocolli separati esterni a tale documento.
Operazioni ed esempi verificati
GET /api/v1
Scopo: restituisce la versione, le risorse disponibili e gli ambiti del modulo abilitato.
Autorizzazione: una chiave API valida. Chiave API attiva e policy di destinazione consentita; i non amministratori sono limitati agli abbonamenti creati da questa chiave, mentre gli amministratori possono gestirli tutti.
Parametri di query: nessuno.
Corpo: nessun campo di input aggiuntivo; segui l'esempio.
curl --globoff --silent --show-error \
--request GET \
--header "Authorization: Bearer $SIMBIOZA_API_KEY" \
"$BASE_URL/api/v1" | jq '{data: (.data | {name,version,resources,scopes,security}), meta, links}'
Risposta effettiva: HTTP 200. Questo è l'output effettivo del filtro jq mostrato.
{
"data": {
"name": "HeartPhrame API",
"version": "v1",
"resources": [
"users",
"groups",
"audit",
"webhooks",
"notifications",
"page",
"attachment",
"task",
"workspace",
"workspace-search",
"surveys",
"calendar",
"follows"
],
"scopes": [
"users:read",
"users:create",
"users:update",
"users:delete",
"groups:read",
"groups:manage",
"audit:read",
"webhooks:read",
"webhooks:manage",
"notifications:read",
"notifications:write",
"page:read",
"page:write",
"page:publish",
"attachment:read",
"attachment:write",
"task:read",
"task:write",
"workspace:read",
"workspace:manage",
"workspace-search:read",
"surveys:read",
"surveys:write",
"surveys:publish",
"surveys:results",
"surveys:export",
"calendar:read",
"calendar:write",
"follows:read",
"follows:write"
],
"security": {
"authentication": "bearer",
"rate_limit_headers": true,
"idempotency_key_for_writes": true,
"problem_format": "RFC 9457",
"webhooks": {
"enabled": true,
"delivery": "asynchronous",
"signature": "hmac-sha256"
}
}
},
"meta": {
"request_id": "cc6b890db5532c15134ac71575045fb5"
},
"links": {
"self": "/api/v1"
}
}
Errori verificati per questa operazione: 401. Consulta regole condivise per i significati dello stato e le risposte ai problemi.
GET /api/v1/me
Scopo: Restituisce identità, ambiti e dati utente pubblici senza campi password.
Autorizzazione: una chiave API valida. Chiave API attiva e policy di destinazione consentita; i non amministratori sono limitati agli abbonamenti creati da questa chiave, mentre gli amministratori possono gestirli tutti.
Parametri di query: nessuno.
Corpo: nessun campo di input aggiuntivo; segui l'esempio.
curl --globoff --silent --show-error \
--request GET \
--header "Authorization: Bearer $SIMBIOZA_API_KEY" \
"$BASE_URL/api/v1/me"
Risposta effettiva: HTTP 200.
{
"data": {
"key": {
"id": 1,
"public_id": "72ea299cf26253dc485c6a95",
"scopes": [
"users:read",
"users:create",
"users:update",
"users:delete",
"groups:read",
"groups:manage",
"audit:read",
"webhooks:read",
"webhooks:manage",
"notifications:read",
"notifications:write",
"page:read",
"page:write",
"page:publish",
"attachment:read",
"attachment:write",
"task:read",
"task:write",
"workspace:read",
"workspace:manage",
"workspace-search:read",
"surveys:read",
"surveys:write",
"surveys:publish",
"surveys:results",
"surveys:export",
"calendar:read",
"calendar:write",
"follows:read",
"follows:write"
]
},
"user": {
"id": 1,
"login_identifier": "Admin",
"display_name": "Administrator",
"email": "admin@example.test",
"first_name": "Admin",
"last_name": "Simbioza",
"group_ids": [
1
],
"group_keys": [
"administrator"
],
"is_admin": true,
"is_active": true,
"auth_source": "local"
}
},
"meta": {
"request_id": "bd11f1fa32846abeb0f47349982394fb"
},
"links": {
"self": "/api/v1/me"
}
}
Errori verificati per questa operazione: 401, 429. Consulta regole condivise per i significati dello stato e le risposte ai problemi.
GET /api/v1/openapi.json
Scopo: Restituisce OpenAPI 3.1 JSON per i moduli attualmente abilitati.
Autorizzazione: una chiave API valida. Chiave API attiva e policy di destinazione consentita; i non amministratori sono limitati agli abbonamenti creati da questa chiave, mentre gli amministratori possono gestirli tutti.
Parametri di query: nessuno.
Corpo: nessun campo di input aggiuntivo; segui l'esempio.
curl --globoff --silent --show-error \
--request GET \
--header "Authorization: Bearer $SIMBIOZA_API_KEY" \
"$BASE_URL/api/v1/openapi.json" | jq '{openapi, info, path_count: (.paths | length), security, components: {securitySchemes: .components.securitySchemes}}'
Risposta effettiva: HTTP 200. Questo è l'output effettivo del filtro jq mostrato.
{
"openapi": "3.1.0",
"info": {
"title": "HeartPhrame API",
"version": "1.0.0",
"description": "Versioned modular API. Domain ACL is always evaluated in addition to key scopes."
},
"path_count": 77,
"security": [
{
"bearerAuth": []
}
],
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "HeartPhrame API key"
}
}
}
}
Errori verificati per questa operazione: 401. Consulta regole condivise per i significati dello stato e le risposte ai problemi.
Errori e diagnostica
Controllare lo stato HTTP prima di leggere data. Le richieste rifiutate restituiscono application/problem+json, con status, code, detail e request_id. Una risposta 404 per il contenuto privato non conferma se la risorsa esiste. Non disabilitare i controlli delle autorizzazioni o la protezione del modulo Web CSRF per aggirare un errore API. L'autenticazione Bearer è separata dalla sessione web.
| HTTP | Significato |
|---|---|
| 400 | JSON o richiesta non valida |
| 401 | chiave mancante, non valida o non consentita |
| 403 | ambito mancante o autorizzazione corrente |
| 404 | la risorsa non è disponibile per questo utente o è mancante |
| 409 | conflitto di versione, stato o idempotenza |
| 412 | If-Match obsoleto |
| 415 | tipo di contenuto del corpo non vuoto non supportato |
| 422 | campi aziendali non validi o caricamento non supportato |
| 428 | If-Match obbligatorio mancante |
| 429 | limite di richieste raggiunto; rispettare Retry-After |
Senza autenticazione
Risposta effettiva HTTP 401:
{
"type": "about:blank",
"title": "Authentication failed",
"status": 401,
"detail": "Send a valid active API key as a Bearer token.",
"code": "invalid_api_key",
"instance": "/api/v1",
"request_id": "1022fef5ddfad19a8c78dd5c87f8bf70"
}
Precondizione dell'aggiornamento mancante
Risposta effettiva HTTP 428:
{
"type": "about:blank",
"title": "The change precondition was not met",
"status": 428,
"detail": "Read the resource before changing it and send its ETag as If-Match.",
"code": "if_match_required",
"instance": "/api/v1/workspaces/api-ogledno-podrucje",
"request_id": "a0153b5a77ba484de02d0c9e35974996"
}
Stessa chiave, corpo diverso
Risposta effettiva HTTP 409:
{
"type": "about:blank",
"title": "The Idempotency-Key has already been used",
"status": 409,
"detail": "The same key must not be used for different requests.",
"code": "idempotency_key_reused",
"instance": "/api/v1/groups",
"request_id": "622b2c534cf92ddc3f402f0de733122a"
}
Limite di richieste raggiunto
Risposta effettiva HTTP 429:
{
"type": "about:blank",
"title": "Too many API requests",
"status": 429,
"detail": "Wait before the next request.",
"code": "rate_limit_exceeded",
"instance": "/api/v1/me",
"request_id": "a43267398714c9a8ac74f166a959cc41"
}
PHP — un piccolo client completo
Questo è un esempio PHP separato; non è necessario tradurre i comandi curl in codice. Salva la funzione come api-client.php. È richiesta l'estensione PHP cURL. Gli URL di produzione devono utilizzare HTTPS; HTTP è consentito solo per lo sviluppo locale di loopback. La funzione supporta JSON, risposte in più parti e binarie, non segue i reindirizzamenti e genera errori HTTP. Leggi i segreti dal tuo archivio sicuro dei segreti o dalle variabili d'ambiente.
<?php
declare(strict_types=1);
/**
* EN: Calls the REST API; redirects are disabled so credentials stay on the configured host.
* HR: Poziva REST API; preusmjeravanja su isključena kako vjerodajnice ne bi otišle drugom hostu.
*
* @param array<string,mixed>|stdClass|null $body
* @param list<string> $extraHeaders
* @param array<string,string|CURLFile>|null $multipart
* @return array{status:int,headers:array<string,string>,json:mixed,body:string}
*/
function simbiozaApi(
string $baseUrl,
#[SensitiveParameter] string $key,
string $method,
string $path,
array|stdClass|null $body = null,
array $extraHeaders = [],
?array $multipart = null,
): array {
if (!extension_loaded('curl')) {
throw new RuntimeException('PHP cURL extension is required.');
}
$url = parse_url($baseUrl);
$local = in_array($url['host'] ?? '', ['127.0.0.1', 'localhost', '::1'], true);
if (!is_array($url) || !in_array($url['scheme'] ?? '', ['http', 'https'], true)
|| (($url['scheme'] ?? '') !== 'https' && !$local)
|| !isset($url['host']) || isset($url['user']) || isset($url['pass'])
|| isset($url['query']) || isset($url['fragment']) || trim($key) === '') {
throw new InvalidArgumentException('Set a valid HTTPS installation URL and API key.');
}
if (($path !== '/api/v1' && !str_starts_with($path, '/api/v1/'))
|| str_contains($path, "\r") || str_contains($path, "\n")
|| ($body !== null && $multipart !== null)) {
throw new InvalidArgumentException('Use an /api/v1 path and one request-body format.');
}
$headers = ['Accept: application/json', 'Authorization: Bearer ' . $key, ...$extraHeaders];
$options = [
CURLOPT_CUSTOMREQUEST => strtoupper($method),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_CONNECTTIMEOUT => 10,
CURLOPT_TIMEOUT => 60,
];
if ($multipart !== null) {
// EN: cURL supplies the multipart boundary. HR: cURL sam postavlja multipart razdjelnik.
$options[CURLOPT_POSTFIELDS] = $multipart;
} elseif ($body !== null) {
// EN: An empty named-field object must be {}, not []. HR: Prazan objekt polja mora biti {}, ne [].
$options[CURLOPT_POSTFIELDS] = json_encode($body === [] ? new stdClass() : $body, JSON_THROW_ON_ERROR);
$headers[] = 'Content-Type: application/json';
}
$responseHeaders = [];
$options[CURLOPT_HTTPHEADER] = $headers;
$options[CURLOPT_HEADERFUNCTION] = static function ($handle, string $line) use (&$responseHeaders): int {
if (str_contains($line, ':')) {
[$name, $value] = explode(':', $line, 2);
$responseHeaders[strtolower(trim($name))] = trim($value);
}
return strlen($line);
};
$handle = curl_init(rtrim($baseUrl, '/') . $path);
curl_setopt_array($handle, $options);
$raw = curl_exec($handle);
if ($raw === false) {
$message = curl_error($handle);
unset($handle);
throw new RuntimeException('HTTP transport failed: ' . $message);
}
$status = (int)curl_getinfo($handle, CURLINFO_RESPONSE_CODE);
unset($handle);
$json = str_contains($responseHeaders['content-type'] ?? '', 'json') && $raw !== ''
? json_decode($raw, true, 512, JSON_THROW_ON_ERROR) : null;
if ($status >= 400) {
$detail = is_array($json) ? (string)($json['detail'] ?? 'Request rejected') : 'Request rejected';
$requestId = $responseHeaders['x-request-id'] ?? '';
throw new RuntimeException("HTTP $status: $detail (request_id=$requestId)");
}
return ['status' => $status, 'headers' => $responseHeaders, 'json' => $json, 'body' => $raw];
}
Utilizzo (impostare prima le variabili di ambiente da Preparazione):
<?php
require __DIR__ . '/api-client.php';
$base = (string)getenv('BASE_URL');
$key = (string)getenv('SIMBIOZA_API_KEY');
$reply = simbiozaApi($base, $key, 'GET', '/api/v1/me');
echo $reply['json']['data']['user']['display_name'], PHP_EOL;
Output effettivo sull'account amministratore sintetico:
Administrator
Passare i campi denominati come quinto argomento per una scrittura JSON; utilizzare [] per un oggetto vuoto (l'helper lo codifica come {}). Aggiungi ['If-Match: ' . $etag] come sesto argomento per ETag. Multiparte è il settimo argomento, ad esempio ['attachment' => new CURLFile(__DIR__ . '/notes.txt')], con il quinto argomento null. Non impostare manualmente il tipo di contenuto multiparte. Salva file con file_put_contents() utilizzando body; decodificato JSON è in json. Percorsi delle risorse, payload e autorizzazioni sono gli stessi degli esempi di curl negli altri capitoli.
Commentaires
0Il n'y a pas encore de commentaires.
Vous devez vous connecter pour ajouter un commentaire.