User interface

Standardized patterns developers can follow to create a consistent and user-friendly experience

Introduction

This section provides a curated set of user interface patterns to help developers build consistent, intuitive, and accessible user experiences.

Each pattern addresses a common scenario — such as navigation, selection, input, and feedback — with instructions and implementation examples.

Combo boxes and search modals

When you implement a user interface feature that allows a user to find an item in a collection, if you need to select data from the API, then use the Search endpoint for the collection.

A search query is specifically designed for this purpose.

• It selects the minimum number of columns required from the database to find matching criteria.

• It returns the minimum number of properties required for typical search results.

• Therefore, it is optimized for server-side performance and download speed.

For example, if you are building a combo box in React to find and select a gradebook, then use the Search endpoint in the API:

progress/gradebooks/search

For details, refer to the OpenAPI Specification

Sending queries to the API

The API provides support for several distinct types of database query. Here is a summary of the purpose (and intended developer use case) for each type of query:

Query Type	Query Purpose	API Endpoint Template
Assert	Checks for the existence of one specific item in a collection using its primary key (returns true or false)	HEAD api/collection/{guid}
Collect	Finds matching items in a collection (returns a list of heavyweight models, suitable for a detailed view of each item in a user interface; also suitable for integration with other systems)	GET or POST api/collection
Count	Counts the matching items in a collection (returns an integer)	GET or POST api/collection/count
Retrieve	Finds one specific item in a collection using its primary key (returns a heavyweight model suitable for a detailed view of the item in a user interface)	GET api/collection/{guid}
Search	Find matching items in a collection (return a list of lightweight models intended for search results, combo boxes, lookups, etc.)	GET or POST api/collection/search