Query REST Web API

you are here (click to zoom) - discover the stack

Every VisualQuery you create has a REST URL. If you set the permissions, you can then read from the Query through REST. You can also pass query-parameters in the URL. Queries are Read APIs.

Standard Query Calls

The Query endpoint can be accessed on

• .../app/auto/query/[your-query-name] when you're accessing a query of the current App (from a dnn-page with this module), as then 2sxc uses auto-detect
• .../app/[app-folder]/query/[your-query-name] using this endpoint from external (other module, other page, other website) as then auto-detect can't work.

👉 read more about different URLs depending on how you access it

Read Only Certain Streams

A query may have many streams that your client may not necessarily need. To limit the results to only specific streams, add one or more stream names to the URL. If you need multiple streams, separate them with commas:

.../app/auto/query/[your-query-name]/Default

.../app/auto/query/[your-query-name]/[your-stream-name]

.../app/auto/query/[your-query-name]/[your-stream-name-1],[your-stream-name-2]

You can also select one or more streams using the stream query parameter:

.../app/auto/query/[your-query-name]?stream=Default

.../app/auto/query/[your-query-name]?stream=[your-stream-name]

.../app/auto/query/[your-query-name]?stream=[your-stream-name-1],[your-stream-name-2]

When exactly one stream is explicitly selected, unprefixed OData parameters such as $select, $filter, $orderby, $top, and $skip apply to that selected stream:

.../app/auto/query/[your-query-name]/[your-stream-name]?$filter=Status eq 'Published'&$orderby=Title

.../app/auto/query/[your-query-name]?stream=[your-stream-name]&$top=10&$select=Field1,Field2

These options are merged per option into the selected stream's OData settings. This means [your-stream-name]$filter=Status eq 'Published' still overrides a bare $filter, while a bare $orderby=Title or $top=10 can still apply if no prefixed value for that option exists.

This also applies when multiple OData options are combined. For example, $select=Field1,Field2&$filter=Status eq 'Published'&$orderby=Title&$top=10 will still return only Field1 and Field2 for the selected stream.

If you need different values per stream, use stream-specific parameters such as [your-stream-name]$filter=Status eq 'Published', [your-stream-name]$orderby=Title, or [your-stream-name]$select=Field1,Field2.

If you request multiple streams, do not rely on bare OData options. In that case, use prefixed parameters such as [your-stream-name-1]$filter=... and [your-stream-name-2]$select=....

HTTP GET only

Note that Query endpoints only support the http-verb GET.

Naming Recommendations

As the query-name is used in the path it's best-practice to use query-names without spaces and special characters. You can get it to work even with such specials, but we recommend you don't do that for simplicity.

POST with GUID filter (WIP)

In 2sxc 11.20 we're experimenting with a post-access to the query which will allow you to also specify GUIDs to filter. This is not final yet.

Setting Security

Querying a query requires read-permissions on that query.

History

1. Introduced Content-REST API in 2sxc 5.x
2. Queries introduced ca. 2sxc 6
3. Query-API enhanced with Polymorph Editions in 2sxc 9.35 (allowing subfolder/api)
4. Option to provide GUIDs to limit what is returned 2sxc 11.20 WIP