RESTful data source

By default, a data source is consumed inside Casewhere — by widgets, workflows, and worker-site components. A RESTful data source is a data source that you additionally expose over HTTP, so custom frontend code in a worker site can query it directly and receive JSON. Use it when a custom widget or component needs ad-hoc, filtered, paged reads of a data source outside the standard widget/workflow data flow.

Enable REST access

REST access is configured per data source, and the data source must be saved first (the Security tab only appears in edit mode).

Open the data source and go to the Security tab.
Turn on Access From Worker Site.
Protect the data source with one or more Server access rules. Add named rules in the rule grid, and/or provide an inline Worker Site Access Rule expression.

Important: Turning on Access From Worker Site without an access rule exposes the data source to any authenticated worker-site user. Always pair the toggle with an access rule.

Access rules for a data source are Server rules: their C# expression returns an AccessMode (Read, Write, or Deny), evaluated against the worker-site user via @user. If any attached rule returns Deny, the request is rejected.

#predicate
if (@user.Contains("Roles", "admin")) { return AccessMode.Write; }
return AccessMode.Read;

See access rules for the full rule model.

Query the data source

A worker site reaches a RESTful data source through two endpoints, both under the worker-site API base api/v0.1. Every request must carry the worker-site session headers Authorization (the user token) and WorkerSiteId. When you use the built-in client (see below), these headers are added for you.

Search

POST api/v0.1/data-source/{dataSourceName}/data

Request body:

Field	Type	Description
`filter`	object	A flat map of field → value. A scalar value matches by equality; an array matches any value in the list (`IN`). Nested objects are not allowed.
`fields`	string[]	Required. The field names to return (the projection).
`skip`	number	Paging offset. Default `0`.
`take`	number	Page size. Default `0` (no limit applied).
`includeTotal`	boolean	When `true`, the response `total` is populated. Default `false`.

Response (HTTP 200):

Field	Type	Description
`data`	object[]	The matching data objects, projected to the requested `fields`.
`total`	number	The total match count (only when `includeTotal` is `true`).
`metadata`	object	Per-field type metadata for the projected fields (e.g. enum information).
`isSearchLimitExceeded`	boolean	Whether the configured search limit was exceeded.

Load by id

GET api/v0.1/data-source/{dataSourceName}/{id}

Returns a single data object.

Worker-site client example

The worker-site framework ships an Angular service, DataSourceService (module cw.core), that calls these endpoints and adds the authentication headers automatically. Use it from your custom widget or component code.

angular.module('cw.core').controller('MyWidgetController', ['DataSourceService', function (DataSourceService) {
    DataSourceService.search('EmployeesWithDepartments', {
        filter: { DepartmentId: '9f1c0b6e-...' },   // scalar = equals; array = IN
        fields: ['Id', 'Name', 'DepartmentName'],
        skip: 0,
        take: 25,
        includeTotal: true
    }).then(function (result) {
        // result.data     -> [{ Id, Name, DepartmentName }, ...]
        // result.total    -> matching count (because includeTotal = true)
        // result.metadata -> per-field type metadata
    });
}]);

To load a single object by id:

DataSourceService.loadDataObject('EmployeesWithDepartments', dataObjectId)
    .then(function (dataObject) { /* ... */ });

Note: DataSourceService is intended for your own custom widgets and components. Stock grid and list widgets load their data through the internal page-component path, not through this service.

Security model

A RESTful data source is protected by several layers, all of which must pass:

Worker-site session. The endpoint sits behind worker-site authentication. Requests without a valid Authorization token and WorkerSiteId (matching an active, non-expired session) are rejected.
The Access From Worker Site toggle. If it is off, the request fails with 401 Unauthorized — the toggle is a hard on/off switch.
Access rules. Attached Server rules and the optional inline Worker Site Access Rule are evaluated for the request; a Deny from any rule blocks it.

The implicit data filters that apply to all Casewhere queries still apply — for example, only data objects in the Created case state are returned.