Vai al contenuto
Sursa Developers

GET/v1/catalog/services

Elencare i servizi del catalogo

list_catalog_services

Restituisce le voci del catalogo globale dei servizi esterni (SaaS e fornitori): una ricerca per sottostringa, senza distinzione tra maiuscole e minuscole, nel nome, nel gruppo o nel dominio del sito web, un filtro per categoria e la paginazione. Il conteggio totale per il filtro è nell’intestazione X-Total-Count. Il catalogo è condiviso da tutte le organizzazioni ed è disponibile per qualsiasi utente che ha effettuato l’accesso. I suoi dati sono distribuiti con Sursa e vengono aggiornati a ogni release (la versione è in GET /v1/catalog/categories e nel campo version dell’icon_url di ogni voce).

Autenticazione

Invia una chiave API nell’intestazione Authorization: Authorization: Bearer <chiave>.

Parametri di query

  • qstring | null

    Sottostringa del nome, del gruppo o del dominio del sito web (senza distinzione tra maiuscole e minuscole).

    length ≤ 200

  • categorystring | null

    Slug della categoria (GET /v1/catalog/categories).

  • offsetinteger

    Predefinito: 0≥ 0

  • limitinteger

    Predefinito: 50≥ 1, ≤ 500

  • cursorstring

    Cursore della pagina successiva, preso da X-Next-Cursor o da next_cursor della risposta precedente con gli stessi filtri; contiene la dimensione della pagina. Insieme a offset: 422 validation.failed; un cursore di un altro elenco, con altri filtri o malformato: 400 api.cursor_invalid.

    length ≤ 512

Parametri di intestazione

  • X-View-Asstring

    Solo per le chiavi API con il ruolo admin. Esegue la richiesta come il profilo dati <profile>[:viewer|verifier|editor], ad esempio employee:viewer. La chiave di installazione non può usare questa intestazione (403).

Parametri cookie

  • kb_view_asstring

    Cookie della modalità “View as” per una sessione. POST /auth/view-as lo imposta e DELETE /auth/view-as lo cancella.

Risposte

200Risposta riuscita

Intestazioni della risposta

  • Link

    Indirizzo della pagina successiva, <…>; rel="next". Se l’intestazione manca, questa è l’ultima pagina.

  • X-Next-Cursor

    Cursore della pagina successiva per il parametro cursor. Se l’intestazione manca, questa è l’ultima pagina.

  • X-Total-Count

    Numero totale di elementi che corrispondono al filtro, indipendentemente da limit e offset.

  • RateLimit-Policy

    Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.

  • RateLimit

    Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).

  • X-RateLimit-Remaining

    Richieste rimanenti nel limite più restrittivo.

  • X-RateLimit-Reset

    Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

array of CatalogService
  • categorystringobbligatorio

    Slug della categoria (GET /v1/catalog/categories).

  • description_enstring | nullobbligatorio

    Breve descrizione in inglese. null se non c’è una descrizione.

  • domainstring | nullobbligatorio

    Dominio del sito web senza www.. null se non c’è un sito web.

  • group_namestring | nullobbligatorio

    Gruppo (fornitore) se il servizio fa parte di una famiglia di prodotti, ad esempio Atlassian; altrimenti null.

  • iconbooleanobbligatorio

    Indica se un’icona è inclusa in Sursa.

  • icon_urlstring | nullobbligatorio

    URL dell’icona (/v1/catalog/services/{service_id}/icon?v=… o un indirizzo esterno configurato dall’installazione). null se non c’è un’icona.

  • idstring (uuid)obbligatorio
  • namestringobbligatorio
  • slugstringobbligatorio
  • websitestring | nullobbligatorio

    URL del sito web (https://…) o null.

401Non sono state inviate credenziali (né un cookie di sessione né una chiave API), oppure la chiave non è stata trovata.

Intestazioni della risposta

  • RateLimit-Policy

    Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.

  • RateLimit

    Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).

  • X-RateLimit-Remaining

    Richieste rimanenti nel limite più restrittivo.

  • X-RateLimit-Reset

    Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: Error

403L’azione non è consentita: il ruolo non è sufficiente, manca l’accesso alla raccolta o alla scheda, la richiesta viene eseguita in modalità “View as”, oppure l’organizzazione è sospesa o eliminata (`detail` è un oggetto con `code: org_suspended | org_deleted`).

Intestazioni della risposta

  • RateLimit-Policy

    Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.

  • RateLimit

    Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).

  • X-RateLimit-Remaining

    Richieste rimanenti nel limite più restrittivo.

  • X-RateLimit-Reset

    Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: Error

422Errore di validazione: il corpo o i parametri non corrispondono allo schema (`detail` è un elenco di errori di validazione), oppure il valore di un parametro è fuori dall’intervallo ammesso (`detail` è un messaggio).

Intestazioni della risposta

  • RateLimit-Policy

    Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.

  • RateLimit

    Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).

  • X-RateLimit-Remaining

    Richieste rimanenti nel limite più restrittivo.

  • X-RateLimit-Reset

    Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: Error

429Troppe richieste (`api.rate_limited`), la quota dell’organizzazione per il minuto, il giorno o il mese è esaurita (`api.quota_exceeded`; `error.details` contiene `quota`, `limit` e `reset_at`), è stato raggiunto il limite dell’organizzazione, oppure il servizio delle risposte è occupato (`answers.engine_busy`). Attendi il tempo indicato nell’intestazione `Retry-After`.

Intestazioni della risposta

  • Retry-After

    Numero di secondi da attendere prima di ripetere la richiesta.

  • RateLimit-Policy

    Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.

  • RateLimit

    Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).

  • X-RateLimit-Remaining

    Richieste rimanenti nel limite più restrittivo.

  • X-RateLimit-Reset

    Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: Error

Codici di errore

Codici che questo endpoint può restituire in error.code, oltre ai codici generali di ogni richiesta.

Limiti di frequenza

Le risposte contengono le intestazioni RateLimit e RateLimit-Policy e le precedenti X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Una risposta 429 contiene Retry-After in secondi: attendi e riprova.

← catalog · Riferimento API