Getting started¶

Install¶

F# / .NETJavaScript / TypeScriptPython

dotnet add package DataHubClient

npm install @nfdi4plants/datahub-client

pip install datahub-client

The npm package includes JavaScript ES modules and TypeScript declarations. TypeScript discovers the declarations automatically; no separate types package or TypeScript runtime is required. Both languages use the same imports and run the same JavaScript, using native fetch in modern browsers or Node.js. The shared JavaScript / TypeScript tabs work in either language. See TypeScript setup for compiler configuration, inferred types, and explicit type imports.

Create a client¶

A DataHubClient needs the DataHub root URL (without the /api/v4 suffix) and an Authentication value:

F# / .NETJavaScript / TypeScriptPython

#r "nuget: DataHubClient"

open DataHubClient

let url = "https://git.nfdi4plants.org"

// PersonalAccessToken, OAuthToken, and JobToken cover the GitLab credential types.
let auth = Authentication.PersonalAccessToken "your-datahub-pat"

// The client defaults to the HTTP transport built for the host runtime;
// assign `client.Http` to substitute your own (retries, proxies, tests).
let client = DataHubClient(url, auth)

printfn $"DataHubClient ready against {url}"

import { DataHubClient } from "@nfdi4plants/datahub-client";
import { Authentication } from "@nfdi4plants/datahub-client/Http/Authentication.js";

const url = "https://git.nfdi4plants.org";

// PersonalAccessToken, OAuthToken, and JobToken cover the GitLab credential types.
const auth = Authentication.PersonalAccessToken("your-datahub-pat");

// The client defaults to the HTTP transport built for the host runtime;
// assign `client.Http` to substitute your own (retries, proxies, tests).
const client = new DataHubClient(url, auth);

console.log(`DataHubClient ready against ${url}`);

from datahub_client import DataHubClient, Authentication

url = "https://git.nfdi4plants.org"

# PersonalAccessToken, OAuthToken, and JobToken cover the GitLab credential types.
auth = Authentication.PersonalAccessToken("your-datahub-pat")

# The client defaults to the HTTP transport built for the host runtime;
# assign `client.Http` to substitute your own (retries, proxies, tests).
client = DataHubClient(url, auth)

print(f"DataHubClient ready against {url}")

Migrating collection types to 0.7.0

Version 0.7.0 changes public collection results, arguments, and properties to ResizeArray<T> in F#. Compared with 0.6.0, use .Count instead of .Length for these collections, and ResizeArray [ ... ] when constructing them. For example, custom transports return HttpResponse(200, "[]", ResizeArray [ "Content-Type", "application/json" ]). JavaScript and TypeScript consumers use ordinary arrays, including arrays of [name, value] pairs for HTTP headers; no Fable collection helpers are needed.

Authentication¶

Authentication selects the authentication header for each request. Use Anonymous() for public resources without credentials, or a factory for one of the GitLab credential types. Anonymous requests omit the authentication header and retain the client-version header.

Factory	Header	Use for
`Authentication.Anonymous`	none	public resources
`Authentication.PersonalAccessToken`	`PRIVATE-TOKEN`	personal access tokens
`Authentication.OAuthToken`	`Authorization: Bearer`	OAuth 2.0 access tokens
`Authentication.JobToken`	`JOB-TOKEN`	CI/CD job tokens

Resource APIs¶

The client is a facade over one API object per GitLab resource area: client.Users, client.Projects, client.Repository, client.Files, client.Issues, client.MergeRequests, client.Packages, and client.Validation (ARC validation results). Every call is async — Async in F#, Promise in JavaScript and TypeScript, awaitable in Python.

client.Users.GetCurrentAsync() resolves the identity behind the configured credential, and is the only call that populates User.Email — GitLab omits it on users embedded in issues, merge requests, notes, and commits.

See Resource API for calls in all four languages and the API reference for the full surface.

List every public project¶

Projects.ListAllAsync retrieves all matching projects in ascending ID order using keyset pagination. It accepts optional search, simple, and visibility filters. Request failures or nonadvancing project IDs raise an error rather than returning an incomplete list. It requests pages of up to 100 projects and continues until the server returns an empty page. Projects.ListAsync still retrieves one page.

Anonymous clients can only see public projects. With a credential, omit visibility to list every project visible to that credential, or use "public", "internal", or "private" to restrict the results. search filters project names and paths; simple requests the compact project representation.

F# / .NETJavaScript / TypeScriptPython

#r "nuget: DataHubClient"

open DataHubClient

let url = "https://git.nfdi4plants.org"
let publicClient = DataHubClient(url, Authentication.Anonymous())

let projects =
    publicClient.Projects.ListAllAsync(visibility = "public")
    |> Async.RunSynchronously

printfn $"Found {projects.Count} public projects"

import { DataHubClient } from "@nfdi4plants/datahub-client";
import { Authentication } from "@nfdi4plants/datahub-client/Http/Authentication.js";

const url = "https://git.nfdi4plants.org";
const publicClient = new DataHubClient(url, Authentication.Anonymous());

const projects = await publicClient.Projects.ListAllAsync(undefined, undefined, "public");
console.log(`Found ${projects.length} public projects`);

import asyncio
from datahub_client import DataHubClient, Authentication

url = "https://git.nfdi4plants.org"
public_client = DataHubClient(url, Authentication.Anonymous())


async def list_public_projects():
    return await public_client.Projects.ListAllAsync(visibility="public")


projects = asyncio.run(list_public_projects())
print(f"Found {len(projects)} public projects")

In JavaScript and TypeScript, use undefined for optional parameters you want to skip. Python supports named arguments; F# uses named optional arguments as shown above.

How this example is checked

CI runs these samples with canned HTTP responses for two project pages and an empty final page, so the checks need no DataHub credentials or network access. The complete sample files include the offline setup and verify pagination and anonymous requests.