API klíče a dokumentace: Automatizujte práci se záložkami

Chcete integrovat StackLinker do svých nástrojů nebo automatizovat správu záložek? Naše API vás vybaví vším potřebným – od ověření totožnosti přes čtení dat až po vytváření a úpravu záložek. V tomto článku vás provedeme nastavením API klíčů a představíme dokumentaci.

Proč používat API?

API otevírá nové možnosti:

• Automatizace – skripty pro hromadné přidávání záložek, migrace z jiných nástrojů
• Integrace – napojení na Slack, Notion, nástroje pro správu projektů
• Vlastní nástroje – CLI, desktopové aplikace nebo mobilní doplňky ke StackLinkeru
• Backup a export – pravidelné zálohy struktury záložek do vlastního úložiště

Jak vygenerovat API klíč

API klíče spravujete v Profilu → API klíče (v anglickém rozhraní: Profile → API Keys). Přihlaste se do svého účtu a v postranním menu najdete sekci API Keys.

Při vytváření nového klíče zadáte:

1. Název – pro snadnou identifikaci (např. „Skript pro backup“, „Slack integrace“)
2. Platnost – volitelně počet dnů, po které klíč platí (prázdné = bez omezení)
3. Oprávnění (scopes) – read pro čtení, write pro zápis a úpravy

Důležité: Token se zobrazí pouze jednou při vytvoření. Uložte si ho na bezpečné místo – po zavření dialogu ho už nebude možné znovu zobrazit. Pro každý nový přístup vytvořte nový klíč.

Ověření v požadavcích

Všechny API požadavky vyžadují ověření. Předávejte API klíč v hlavičce Authorization:

Authorization: Bearer YOUR_API_KEY

Bez platného klíče obdržíte chybu 401 Unauthorized. Pokud klíč expiroval nebo byl odvolán, vygenerujte nový v profilu.

GraphQL endpoint

StackLinker používá GraphQL – jeden endpoint pro všechny operace. Základní URL získáte z dokumentace nebo z nastavení vaší instance (např. `https://stacklinker.net/api`).

POST {BASE_URL}/api/graphql
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "query": "query { me { id email nickname } }"
}

GraphQL umožňuje přesně specifikovat, jaká data potřebujete – žádná nadbytečná odpověď, žádné přetěžování. V jednom požadavku můžete načíst uživatele, pracovní prostory, složky i záložky.

Co nabízí dokumentace

V sekci Docs → API (/cs/docs/api) najdete:

• Interaktivní GraphiQL playground – testujte dotazy přímo v prohlížeči
• Referenční dokumentaci – přehled dotazů a mutací (me, workspaces, folders, bookmarks, …)
• Příklady v cURL, Node.js, Pythonu a PHP
• Možnost stáhnout GraphQL schéma pro generování typů a klientů

Pro rychlý start stačí otevřít playground, vložit svůj API klíč a vyzkoušet například dotaz `me` nebo `workspaces`.

Příklady použití

Načtení pracovních prostorů

query Workspaces {
  workspaces(first: 10, after: null) {
    edges {
      node {
        id
        name
        isPersonal
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    totalCount
  }
}

Vytvoření složky

mutation CreateFolder($workspaceId: ID!, $name: String!) {
  createFolderFolder(input: {
    workspaceId: $workspaceId
    name: $name
    parentId: null
  }) {
    folder {
      id
      name
    }
  }
}

Přidání záložky

mutation CreateBookmark($workspaceId: ID!, $folderId: ID!, $name: String!, $url: String!) {
  createBookmarkBookmark(input: {
    workspaceId: $workspaceId
    folderId: $folderId
    name: $name
    url: $url
  }) {
    bookmark {
      id
      name
      url
    }
  }
}

Bezpečnostní doporučení

• Nesdílejte klíče – každá integrace by měla mít vlastní klíč s příslušnými oprávněními
• Používejte read-only tam, kde stačí – pro skripty, které jen čtou data, nastavte pouze scope `read`
• Omezte platnost – u dočasných integrací nastavte expiraci
• Klíče průběžně revokujte – v profilu můžete kdykoliv odvolat nepoužívané klíče

Další kroky

1. Vygenerujte si API klíč v Profile → API Keys
2. Otevřete Docs → API a vyzkoušejte playground
3. Stáhněte schéma a vygenerujte klienta ve své oblíbené technologii
4. Začněte s jednoduchým dotazem `me` a postupně přidávejte složitější operace

Máte dotazy nebo návrhy na vylepšení API? Napište nám přes kontaktní formulář.