FRAGMENT

Documentation

C Install the SDK#

FRAGMENT publishes SDKs in TypeScript, Go, and Ruby. The SDKs are open-source, implement authentication, and come with predefined GraphQL queries to help you get started.

a. Setup the CLI

#

The FRAGMENT CLI is used to generate GraphQL queries specific to your Schema. The SDKs use the generated queries to give you a strongly-typed interface for posting Ledger Entries defined in your Ledger.

Install the CLI using Homebrew:

brew tap fragment-dev/tap &&\
  brew install fragment-dev/tap/fragment-cli

Authenticate the CLI to your FRAGMENT workspace, run the login command:

fragment login

b. TypeScript

#

The TypeScript Node SDK is available at @fragment-dev/node-client.

Using npm
npm install --save @fragment-dev/node-client
Using yarn
yarn add @fragment-dev/node-client

Create an API client in the FRAGMENT dashboard. Initialize the SDK using the credentials:

import {
  createFragmentClient
} from '@fragment-dev/node-client';

const fragment = createFragmentClient({
  params: {
    clientId: "<Client ID>",
    clientSecret: "<Client Secret>",
    apiUrl: "<API URL>",
    authUrl: "<OAuth URL>",
    scope: "<OAuth Scope>",
  },
});

// Verify the SDK is authenticated by retrieving
// the workspace
const { workspace } = await fragment.getWorkspace();
console.log('Workspace Name:', workspace.name);

Read the SDK's README for additional code examples.

Generate Queries#

This workflow is a two-step process:

  1. Use the CLI to generate GraphQL queries.
  2. Use the SDK to translate these queries to a TypeScript GraphQL client you can embed within your application.

Run the get-schema CLI command to download your Schema locally to fragment/schema.jsonc:

fragment get-schema --output=fragment/schema.jsonc

Run the gen-graphql CLI command to generate the GraphQL queries:

fragment gen-graphql \
  --path=fragment/schema.jsonc \
  --output=fragment/queries.graphql

This will create a queries.graphql file which you will use to generate the GraphQL client.

Generate Client#

Run the TypeScript codegen to generate the GraphQL client code:

Using npx
npx fragment-node-client-codegen \
  --input=fragment/queries.graphql \
  --outputFilename=fragment/fragment-client.ts
Using yarn
yarn fragment-node-client-codegen \
  --input=fragment/queries.graphql \
  --outputFilename=fragment/fragment-client.ts

Pass the getSdk function from the generated file to createFragmentClient to use the queries:

import {
  createFragmentClient
} from "@fragment-dev/node-client";

import {
  getSdk
} from './fragment/fragment-client';

const fragment = createFragmentClient({
  params: {
    clientId: "<Client ID>",
    clientSecret: "<Client Secret>",
    apiUrl: "<API URL>",
    authUrl: "<OAuth URL>",
    scope: "<OAuth Scope>",
  },
  getSdk,
});

// The returned client includes the
// pre-defined queries as well as
// the queries generated by the CLI.
await fragment.Post_YourLedgerEntry({});

c. Python

#

The Python SDK is available at github.com/fragment-dev/fragment-python.

To install:

Using pip
pip install fragment-python
Using poetry
poetry add fragment-python

Create an API client in the FRAGMENT dashboard. Initialize the client using the credentials:

from fragment.sdk.client import Client

client = Client(
  client_id="<Client ID>",
  client_secret="<Client Secret>",
  api_url="<API URL>",
  auth_url="<OAuth URL>",
  auth_scope="<OAuth Scope>",
)

async def print_workspace():
  response = await client.get_workspace()
  print(response.workspace.name)

import asyncio
loop.get_event_loop().run_until_complete(
  print_workspace())

Read the SDK's README for additional code examples.

Generate Queries#

This workflow is a two-step process:

  1. Use the CLI to generate GraphQL queries.
  2. Use the SDK to translate these queries to a Python GraphQL client you can embed within your application.

Run the get-schema CLI command to download your Schema locally to fragment/schema.jsonc:

fragment get-schema --output=fragment/schema.jsonc

Run the gen-graphql CLI command to generate the GraphQL queries:

fragment gen-graphql \
  --path=fragment_lib/schema.jsonc \
  --output=fragment_lib/queries/queries.graphql

This will create a queries.graphql file which you will use to generate the GraphQL client.

Generate Client#

Run the Python codegen to generate the Python GraphQL client code:

fragment-python-client-codegen \
  --input-dir=fragment_lib/queries \
  --target-package-name=sdk \
  --output-dir=fragment_lib

You can optionally provide the --sync flag to generate a synchronous client.

Instantiate the generated client from fragment_lib/sdk/client.py:

from .fragment_lib.sdk.client import Client

# The generated client includes the pre-defined
# queries as well as the queries generated by the CLI.
client = Client(
  client_id="<Client ID>",
  client_secret="<Client Secret>",
  api_url="<API URL>",
  auth_url="<OAuth URL>",
  auth_scope="<OAuth Scope>",
)

async def print_workspace_and_post_entry():
  response = await client.get_workspace()
  print(response.workspace.name)

  await client.post_your_ledger_entry_type(...)

import asyncio
loop.get_event_loop().run_until_complete(
  print_workspace_and_post_entry())

d. Go

#

The Go SDK is available at github.com/fragment-dev/fragment-go.

To install, run:

go get 'github.com/fragment-dev/fragment-go'

Create an API client in the FRAGMENT dashboard. Initialize the SDK using the credentials:

package main

import (
  "context"
  "fmt"

  "github.com/fragment-dev/fragment-go/auth"
  "github.com/fragment-dev/fragment-go/queries"
)

func main() {
  ctx, err := auth.GetAuthenticatedContext(
    context.Background(),
    &auth.GetTokenParams{
      ClientID: "<Client ID>",
      ClientSecret: "<Client Secret>",
      ApiUrl: "<API URL>",
      AuthUrl: "<OAuth URL>",
      Scope: "<OAuth Scope>",
    }
  )
  if err != nil {
    fmt.Println(err)
    return
  }

  // Verify the SDK is authenticated by retrieving
  // the workspace
  response, _ := queries.GetWorkspace(ctx)
}

Read the SDK's README for additional code examples.

Generate Queries#

This workflow is a two-step process:

  1. Use the CLI to generate GraphQL queries.
  2. Use the SDK to translate these queries to methods you can embed within your application.

Run the get-schema CLI command to download your Schema locally to fragment/schema.jsonc:

fragment get-schema --output=fragment/schema.jsonc

Run the gen-graphql CLI command to generate the GraphQL queries:

fragment gen-graphql \
  --path=fragment/schema.jsonc \
  --output=fragment/queries.graphql

This will create a queries.graphql file which you will use to generate the corresponding Go methods.

Generate Code#

Run the Go SDK codegen to generate methods for each GraphQL query:

go run github.com/fragment-dev/fragment-go \
  --input=fragment/queries.graphql \
  --output=fragment/generated.go \
  --package=main

You can then issue the GraphQL request from your main package:

package main

import (
  "context"
  "fmt"

  "github.com/fragment-dev/fragment-go/auth"
)

func main() {
  ctx, err := auth.GetAuthenticatedContext(
    context.Background(),
    &auth.GetTokenParams{
      ClientID: "<Client ID>",
      ClientSecret: "<Client Secret>",
      ApiUrl: "<API URL>",
      AuthUrl: "<OAuth URL>",
      Scope: "<OAuth Scope>",
    }
  )
  if err != nil {
    fmt.Println(err)
    return
  }

  response, _ := Post_YourLedgerEntryType(
    ctx,
    ...
  )
}

e. Ruby

#

The Ruby SDK is available at fragment-dev.

To install, run:

gem install fragment-dev

Create an API client in the FRAGMENT dashboard. Initialize the SDK using the credentials:

require 'fragment_client'

fragment = FragmentClient.new(
  "<Client ID>",
  "<Client Secret>",
  api_url: "<API URL>",
  oauth_url: "<OAuth URL>",
  oauth_scope: "<OAuth Scope>"
)

// Verify the SDK is authenticated by retrieving
// the workspace
workspace = fragment.get_workspace()

Read the SDK's README for additional code examples.

Generate Queries#

This workflow is a two-step process:

  1. Use the CLI to generate GraphQL queries.
  2. Use the SDK to translate these queries to methods you can embed within your application.

Run the get-schema CLI command to download your Schema locally to fragment/schema.jsonc:

fragment get-schema --output=fragment/schema.jsonc

Run the gen-graphql CLI command to generate the GraphQL queries:

fragment gen-graphql \
  --path=fragment/schema.jsonc \
  --output=fragment/queries.graphql

This will create a queries.graphql file which you will provide as input to FragmentClient.

Use custom queries#

Initialize FragmentClient with the extra_queries_filenames keyword argument set to the path of the generated queries.graphql file:

require 'fragment_client'

fragment = FragmentClient.new(
  "<Client ID>",
  "<Client Secret>",
  api_url: "<API URL>",
  oauth_url: "<OAuth URL>",
  oauth_scope: "<OAuth Scope>",
  extra_queries_filenames:
    ["path/to/queries.graphql"]
)

fragment.post_your_ledger_entry_type()

f. Other Languages

#

FRAGMENT exposes a GraphQL API to write and read your data. The latest GraphQL schema is hosted at:

https://api.fragment.dev/schema.graphql

To create an SDK in a language not listed above:

  1. Use the FRAGMENT CLI to generate GraphQL queries from your Schema
  2. Generate an SDK using a GraphQL codegen tool for your langauge
  3. Implement authentication, retry and error handling logic
Generate Queries#

Run the get-schema CLI command to download your Schema locally to fragment/schema.jsonc:

fragment get-schema --output=fragment/schema.jsonc

Run the gen-graphql CLI command to generate the GraphQL queries:

fragment gen-graphql \
  --path=fragment/schema.jsonc \
  --output=fragment/queries.graphql

Provide the optional --include-standard-queries flag to include the set of standard GraphQL queries in the output.

This will create a queries.graphql file which you will provide as input to your codegen tool.

Some codegen tools require each GraphQL query to be in a separate file. You can use the --output-file-per-query flag:

fragment gen-graphql \
  --path=fragment/schema.jsonc \
  --output=fragment/queries \
  --output-file-per-query
Generate SDK#

Use a GraphQL codegen tool to generate the SDK. A list of clients is available on the GraphQL website.

Implement logic#

You will need to implement authentication by customizing the generated SDK. FRAGMENT uses OAuth2's client credentials flow to authenticate API clients. Read the API Authentication section to learn more.

You should also add support for handling errors and retries. See the API Errors section.