Skip to main content
A data source is a service, such as your own API, that components on your canvases may call. Components never reach the network themselves. CanvasView calls the source for them, adds the secret headers you entered, and returns the answer to the component. Admins create and manage data sources. An agent can list them and ask for a new one, but it cannot create one, change one or read its secrets. Members see each source’s name, host and methods on the Data sources page, and are asked to contact an Admin to add or change one. Data sources belong to the organization, so any member’s canvases can use them.

Add a data source

  1. Open Data sources.
  2. Under Add a source, enter a Name, such as orders. Agents and components use this name. It is 2 to 64 lowercase letters, digits and hyphens, starting with a letter, and cannot be changed later.
  3. Enter the Base URL, such as https://api.example.com/v1. It must use HTTPS on a public host, with no query.
  4. Optionally enter a Path prefix, such as /orders. Components can then only call paths under the base URL and this prefix.
  5. Choose the Allowed methods. Only GET is selected by default. POST, PUT, PATCH and DELETE let components write.
  6. Under Secret headers, select Add header for each credential the service needs, such as Authorization. You can add up to 5.
  7. Select Add source.
An account can hold up to 20 data sources.

Use a limited key

Anyone who can open a canvas that uses a source can make it request any path under its base URL and prefix, with any method you allowed. Give each source a key that can do only what those canvases need. Never use an admin or service key.
  • Set a path prefix that covers only what the canvas needs.
  • Allow write methods only when a component must write. Writes work on active canvases only.
  • Add only services you trust. A service that repeats request headers in its answers would show a secret to viewers.

What each party can see

The service sees the viewer’s email only if an Admin turns on Send the viewer’s verified email as X-CanvasView-Viewer on canvases that need sign-in. CanvasView then adds the header on canvases that use sign-in or invitations. It never sends it on link-access canvases. Secret header values are stored encrypted. CanvasView never shows a value again. To change a value, select Edit, enter a new value and select Save source. Leave a stored value empty to keep it.

How a canvas uses a source

A canvas can call a source only when its agent lists the source’s name in the canvas’s dataSources. The canvas then shows viewers which of your sources its components load data from. A canvas that uses a source needs sign-in by default, because anyone who can open it can call the source. See Sharing and access. CanvasView refuses a call when:
  • the canvas does not declare the source, or the method is not allowed;
  • the path leaves the base URL and prefix;
  • a viewer makes more than 60 requests a minute, or a canvas more than 600;
  • the request body is larger than 256 KB, or the answer larger than 1 MB;
  • the source does not answer within 10 seconds, redirects, or answers with something other than JSON or text.

Requests from agents

When an agent needs a source you do not have, it can ask for one with a name, a base URL and a reason. The request appears under Requested by agents on an Admin’s Data sources page, and as an action in your organization’s notifications. Check the address and reason first. An agent asked for it, not a person.
  • To approve it, set up a source with the requested name. This answers the request.
  • To decline it, select Dismiss.

Remove a data source

An Admin selects Remove next to the source. Before confirming, CanvasView lists the live canvases that still declare it. Their components stop reaching the source at once. The organization gets a notification naming those canvases. It clears itself when no live canvas declares the source any more, or when you add the source again.

Developers

Components call a source with useData or fetchData from @canvasview/kit. See Custom components.