A list method is an API operation that retrieves a current collection of selectable or related data. It should return success when no elements match, because an empty result is normally a valid search outcome rather than an error. section 3.4.5
Useful list methods let consumers filter, sort, and paginate results. These controls avoid forcing a consumer to retrieve an entire collection when it needs a narrow slice, such as transactions from a date, location, and amount range. section 9.6
Design a list method around consumer usability, efficiency, and security:
- Return current data when consumers need choices for later operations; account-application flows use list methods to avoid storing outdated services, branches, cards, or account holders. section 10.4.1
- Describe the security-dependent scope explicitly. A list of accounts may vary by account owner, bank advisor, or partner application, rather than exposing every account. section 12.4.2
- Separate collection summaries from detailed resource representations when appropriate; a course list can return identifiers and names while a read operation returns domain, rating, description, and lessons. section 13.11
List accounts with an explicit security scope
GET /accounts can return Account elements containing selected properties such as iban and balance. Its 200 response should state whose accounts are returned: accounts owned by the end user, managed by a bank advisor, or linked to a partner identifier. section 12.4.2
Listing 13.1 “List courses” response
{
"data": [
...
{
"id": "course_1005",
"name": "Advanced Machine Learning"
},
{
"id": "course_1006",
"name": "Financial Accounting",
},
...
]
}
Use the course-list response to compare a compact collection representation with the richer response from GET /courses/{courseId}. section 13.11
