FAQ

Purpose

This page is meant to be a dump of questions and answers for people learning about connectors. The hope is that similar questions can be grouped together and condensed into new wiki articles.

FAQs

What is pagination?

When a user requests data from a server's API, there can be a couple reasons why that data cannot be served quickly and correctly.

• The database that stores the data might shard the data in suboptimal way or take longer to retrieve than the HTTP request's timeout.
• There might be so much data that it cannot fit in the transport layer's format.
• Retrieved data might need to be post processed in a computationally expensive way that the API might want to rate limit in a very fine-grained way. Either way, APIs can have a maximum "chunk" size and expect consumers to iteratively request these chunks by varying the request parameters. APIs can handle these in many ways but these common ways are:
• ask for a "offset" and "count". for example, start at the "0th result" and return a list of 100 items.
• ask for a "start" with or without a count and rely on the server to return a "next" cursor. The server can let the requester know there are no more pages of data by returning fewer items than the user requested or by not returning a value to the "next" cursor.

What is a sync?

Syncing collects all the data about resources, entitlements, and grants, and writes them to a .c1z file.

What is the difference between one-shot mode and service mode?

Connectors can be run to consume the API to find out which users have access to which resources. It just syncs and that's it. The alternative is to create an app on the ConductorOne website and have it sync on a regular cadence (e.g. hourly.) The data can then be consumed in the browser.

What is a .c1z file?

A compressed SQLite database that stores which users have access to which resources. The data inside can be easily opened and read with the baton command in CLI.

What is provisioning?

Adding and removing users' access to resources. The verbs we use are "grant" and "revoke".

In my connector, why is the Entitlements() method empty in users.go?

Users are the thing that are granted an entitlement, they aren't entitlements.

What is a trait?

Marks a resource as behaving a known resource type, like "user", "group", or "role".

What are annotations?

The interface that baton-sdk exposes to connectors is difficult to change because it has so many consumers. Methods like Grant() return an optional list of annotations and an optional error.