Přehled REST API ClearPolicy

REST API ClearPolicy Vám dává přístup z kódu k lidem, skupinám, dokumentům a žádostem o potvrzení Vaší organizace. Všechny endpointy komunikují přes HTTPS a vrací JSON.

Základní URL

https://api.clearpolicy.app/api/v1

Předpona cesty API (/api/v1) je součástí každé URL požadavku. Aktuální a jediná verze je v1.

Ověření

Všechny endpointy vyžadují platný bearer token API. Token předejte v hlavičce Authorization:

Authorization: Bearer YOUR_ACCESS_TOKEN

Návod na vytvoření tokenu najdete v Ověření.

Vaše organizace musí mít aktivní předplatné, nebo být ve zkušebním období. Když zkušební období vypršelo nebo předplatné není aktivní, všechny požadavky API vrátí odpověď 402 Payment Required.

Přístup podle role

Přístup k API se řídí Vaší rolí v ClearPolicy. Vlastníci a správci organizace mohou vytvářet tokeny API a používat endpointy lidí, skupin, dokumentů a žádostí o potvrzení. Tokeny vázané na správce skupiny mohou použít GET /me k ověření tokenu a organizace. Ostatní endpointy REST API vrátí 403 Forbidden.

Formát odpovědí

Všechny odpovědi jsou JSON. Úspěšné odpovědi vrací požadovaný zdroj nebo kolekci přímo v těle odpovědi.

ID

Všechna ID zdrojů jsou ULID — řetězcové identifikátory, které lze řadit lexikograficky. Zapisují se malými písmeny, například:

01kg82xqfx6fvr046d15hnfmjv

Stránkování

Endpointy seznamů vrací stránkované výsledky. Odpověď obsahuje pole data spolu s objekty links a meta:

{
  "data": [...],
  "links": {
    "first": "https://api.clearpolicy.app/api/v1/people?page=1",
    "last": "https://api.clearpolicy.app/api/v1/people?page=5",
    "prev": null,
    "next": "https://api.clearpolicy.app/api/v1/people?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 5,
    "per_page": 25,
    "to": 25,
    "total": 120
  }
}

Výsledky procházíte parametry dotazu page a per_page. per_page přijímá hodnoty od 1 do 100. Výchozí hodnota je 25.

Chyby

Chyby vrací JSON s polem error, které popisuje problém:

{
  "error": "Person not found."
}

Běžné stavové kódy HTTP:

Stav	Význam
`200 OK`	Požadavek uspěl.
`201 Created`	Zdroj byl úspěšně vytvořen.
`400 Bad Request`	Požadavek byl neplatný (např. dokument není zveřejněný).
`401 Unauthorized`	Chybí přístupový token, nebo je neplatný.
`402 Payment Required`	Zkušební období Vaší organizace vypršelo, nebo předplatné není aktivní. Přejděte na stránku fakturace a předplaťte si službu.
`403 Forbidden`	Token nemá potřebná oprávnění.
`404 Not Found`	Požadovaný zdroj ve Vaší organizaci neexistuje.
`422 Unprocessable Entity`	Validace selhala — zkontrolujte parametry požadavku.
`429 Too Many Requests`	Překročen limit počtu požadavků — počkejte a zkuste to znovu.

Omezení počtu požadavků

Každý token API je omezený na 60 požadavků za minutu. Limity platí na token, ne na organizaci. Několik tokenů má proto každý vlastní kvótu. Když limit překročíte, API vrátí 429 Too Many Requests. Odpovědi obsahují hlavičky Retry-After a X-RateLimit-*, abyste věděli, kdy zkusit znovu. Při opakování používejte exponenciální backoff.

Přehled

Me

Lidé

Dokumenty

Skupiny

Žádosti o potvrzení

Přehled REST API ClearPolicy

Základní URL

Ověření

Přístup podle role

Formát odpovědí

ID

Stránkování

Chyby

Omezení počtu požadavků

​Základní URL

​Ověření

​Přístup podle role

​Formát odpovědí

​ID

​Stránkování

​Chyby

​Omezení počtu požadavků

Základní URL

Ověření

Přístup podle role

Formát odpovědí

ID

Stránkování

Chyby

Omezení počtu požadavků