Anar al contingut
Sursa Developers

GET/v1/catalog/services/{service_id}

Obtenir un servei del catàleg

get_catalog_service

Retorna un element del catàleg per ID amb les descripcions en les dues llengües. Un ID desconegut retorna 404 catalog.service_not_found.

Autenticació

Envieu una clau d’API a la capçalera Authorization: Authorization: Bearer <clau>.

Paràmetres de camí

  • service_idstring (uuid)obligatori

    ID de l’element del catàleg de serveis (UUID).

Paràmetres de capçalera

  • X-View-Asstring

    Només per a claus d’API amb el rol admin. Fa la sol·licitud com el perfil de dades <profile>[:viewer|verifier|editor], per exemple employee:viewer. La clau d’instal·lació no pot fer servir aquesta capçalera (403).

Paràmetres de galeta

  • kb_view_asstring

    Galeta del mode «View as» per a una sessió. POST /auth/view-as l’estableix i DELETE /auth/view-as l’esborra.

Respostes

200Resposta correcta

Capçaleres de la resposta

  • RateLimit-Policy

    Límits vigents, en el format de l’esborrany de l’IETF draft-ietf-httpapi-ratelimit-headers: elements separats per comes "<name>";q=<quota>;w=<window in seconds>. key és la freqüència de sol·licituds de la clau d’API (la quota és la ràfega, la finestra és el temps que triga a reomplir-se del tot; per a una sessió és user, sense credencials ip); minute, day i month són les quotes de l’organització per al minut, el dia i el mes naturals en UTC.

  • RateLimit

    El que queda de cada límit de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Límit de l’element més restrictiu de RateLimit-Policy (el que té menys sol·licituds restants).

  • X-RateLimit-Remaining

    Sol·licituds restants dins del límit més restrictiu.

  • X-RateLimit-Reset

    Segons que falten perquè es restableixi el límit més restrictiu.

application/json

Objecte: CatalogService

  • categorystringobligatori

    Identificador curt (slug) de la categoria (GET /v1/catalog/categories).

  • description_enstring | nullobligatori

    Descripció breu en anglès. null si no hi ha descripció.

  • domainstring | nullobligatori

    Domini del lloc web sense www.. null si no hi ha lloc web.

  • group_namestring | nullobligatori

    Grup (proveïdor) si el servei pertany a una família de productes, per exemple Atlassian; altrament, null.

  • iconbooleanobligatori

    Indica si Sursa inclou una icona.

  • icon_urlstring | nullobligatori

    URL de la icona (/v1/catalog/services/{service_id}/icon?v=… o una adreça externa configurada per la instal·lació). null si no hi ha icona.

  • idstring (uuid)obligatori
  • namestringobligatori
  • slugstringobligatori
  • websitestring | nullobligatori

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

401No s’han enviat credencials (ni una galeta de sessió ni una clau d’API), o no s’ha trobat la clau.

Capçaleres de la resposta

  • RateLimit-Policy

    Límits vigents, en el format de l’esborrany de l’IETF draft-ietf-httpapi-ratelimit-headers: elements separats per comes "<name>";q=<quota>;w=<window in seconds>. key és la freqüència de sol·licituds de la clau d’API (la quota és la ràfega, la finestra és el temps que triga a reomplir-se del tot; per a una sessió és user, sense credencials ip); minute, day i month són les quotes de l’organització per al minut, el dia i el mes naturals en UTC.

  • RateLimit

    El que queda de cada límit de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Límit de l’element més restrictiu de RateLimit-Policy (el que té menys sol·licituds restants).

  • X-RateLimit-Remaining

    Sol·licituds restants dins del límit més restrictiu.

  • X-RateLimit-Reset

    Segons que falten perquè es restableixi el límit més restrictiu.

application/json

Objecte: Error

403L’acció no està permesa: el rol és insuficient, no hi ha accés a la col·lecció o a l’entrada, la sol·licitud s’executa en mode «View as», o l’organització està suspesa o eliminada (`detail` és un objecte amb `code: org_suspended | org_deleted`).

Capçaleres de la resposta

  • RateLimit-Policy

    Límits vigents, en el format de l’esborrany de l’IETF draft-ietf-httpapi-ratelimit-headers: elements separats per comes "<name>";q=<quota>;w=<window in seconds>. key és la freqüència de sol·licituds de la clau d’API (la quota és la ràfega, la finestra és el temps que triga a reomplir-se del tot; per a una sessió és user, sense credencials ip); minute, day i month són les quotes de l’organització per al minut, el dia i el mes naturals en UTC.

  • RateLimit

    El que queda de cada límit de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Límit de l’element més restrictiu de RateLimit-Policy (el que té menys sol·licituds restants).

  • X-RateLimit-Remaining

    Sol·licituds restants dins del límit més restrictiu.

  • X-RateLimit-Reset

    Segons que falten perquè es restableixi el límit més restrictiu.

application/json

Objecte: Error

404L’objecte no existeix o no està disponible per a vós. L’API no confirma que existeixi un objecte restringit.

Capçaleres de la resposta

  • RateLimit-Policy

    Límits vigents, en el format de l’esborrany de l’IETF draft-ietf-httpapi-ratelimit-headers: elements separats per comes "<name>";q=<quota>;w=<window in seconds>. key és la freqüència de sol·licituds de la clau d’API (la quota és la ràfega, la finestra és el temps que triga a reomplir-se del tot; per a una sessió és user, sense credencials ip); minute, day i month són les quotes de l’organització per al minut, el dia i el mes naturals en UTC.

  • RateLimit

    El que queda de cada límit de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Límit de l’element més restrictiu de RateLimit-Policy (el que té menys sol·licituds restants).

  • X-RateLimit-Remaining

    Sol·licituds restants dins del límit més restrictiu.

  • X-RateLimit-Reset

    Segons que falten perquè es restableixi el límit més restrictiu.

application/json

Objecte: Error

422Error de validació: el cos o els paràmetres no coincideixen amb l’esquema (`detail` és una llista d’errors de validació), o el valor d’un paràmetre és fora de l’interval permès (`detail` és un missatge).

Capçaleres de la resposta

  • RateLimit-Policy

    Límits vigents, en el format de l’esborrany de l’IETF draft-ietf-httpapi-ratelimit-headers: elements separats per comes "<name>";q=<quota>;w=<window in seconds>. key és la freqüència de sol·licituds de la clau d’API (la quota és la ràfega, la finestra és el temps que triga a reomplir-se del tot; per a una sessió és user, sense credencials ip); minute, day i month són les quotes de l’organització per al minut, el dia i el mes naturals en UTC.

  • RateLimit

    El que queda de cada límit de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Límit de l’element més restrictiu de RateLimit-Policy (el que té menys sol·licituds restants).

  • X-RateLimit-Remaining

    Sol·licituds restants dins del límit més restrictiu.

  • X-RateLimit-Reset

    Segons que falten perquè es restableixi el límit més restrictiu.

application/json

Objecte: Error

429Massa sol·licituds (`api.rate_limited`), s’ha esgotat la quota de l’organització per al minut, el dia o el mes (`api.quota_exceeded`; `error.details` conté `quota`, `limit` i `reset_at`), s’ha arribat al límit de l’organització o el servei de respostes està ocupat (`answers.engine_busy`). Espereu el temps que indica la capçalera `Retry-After`.

Capçaleres de la resposta

  • Retry-After

    Nombre de segons que cal esperar abans de reintentar la sol·licitud.

  • RateLimit-Policy

    Límits vigents, en el format de l’esborrany de l’IETF draft-ietf-httpapi-ratelimit-headers: elements separats per comes "<name>";q=<quota>;w=<window in seconds>. key és la freqüència de sol·licituds de la clau d’API (la quota és la ràfega, la finestra és el temps que triga a reomplir-se del tot; per a una sessió és user, sense credencials ip); minute, day i month són les quotes de l’organització per al minut, el dia i el mes naturals en UTC.

  • RateLimit

    El que queda de cada límit de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Límit de l’element més restrictiu de RateLimit-Policy (el que té menys sol·licituds restants).

  • X-RateLimit-Remaining

    Sol·licituds restants dins del límit més restrictiu.

  • X-RateLimit-Reset

    Segons que falten perquè es restableixi el límit més restrictiu.

application/json

Objecte: Error

Codis d’error

Codis que aquest punt final pot retornar a error.code, a més dels codis generals de totes les sol·licituds.

Límits de freqüència

Les respostes porten les capçaleres RateLimit i RateLimit-Policy i les anteriors X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset. Una resposta 429 té Retry-After en segons: espereu i torneu-ho a provar.

← catalog · Referència de l’API