Document a bit more about query parameters

haskell-api.md

@@ -5,45 +5,71 @@
 Prefer stateless endpoints. Sessions are used to authorize data access, but not
 choose what data to return.
 
-- Good:
-  - `/3/students?schools.id=x,y,z`
-  - `ApiClient.fetch("/3/students", { "schools.id": me.schoolIds })`
-- Bad:
-  - `/3/school-admins/me/students`
-  - `ApiClient.fetch("/3/school-admins/me/students")`
+Good:
+
+- `/3/students?schools.id=x,y,z`
+- `ApiClient.fetch("/3/students", { "schools.id": me.schoolIds })`
+
+Bad:
+
+- `/3/school-admins/me/students`
+- `ApiClient.fetch("/3/school-admins/me/students")`
 
 ## Parameters
 
-We want to :heart: query parameters as a way to keep the number of distinct
-endpoints lower by supporting more complex filtering combinations within each
-endpoints.
+Prefer filtering by query parameter instead of making distinct endpoints
+filtered by their path-pieces.
+
+Good:
+
+- `/3/students?schools.id=x,y,z&teachers.id=a,b,c`
+
+Bad:
+
+- `/3/schools/:id/students`
+- `/3/teachers/:id/students`
+- `/3/schools/:id/teachers/:id/students`
+
+### Operations
+
+For complex filtering, follow an "operation suffix" syntax,
+
+Good:
 
-- Good: `/3/students?schools.id=x,y,z&teachers.id=a,b,c`
-- Bad:
-  - `/3/schools/:id/students`
-  - `/3/teachers/:id/students`
-  - `/3/schools/:id/teachers/:id/students`
-  - etc, forever
+- `status[in]=draft,review`
+- `completed-at[gt]=...&completed-at[lte]=...`
+
+Bad:
+
+- `status=draft&status=review`
+- `from=...&to=...`
+
+Endpoints should support parameters without an operation suffix like `[in]`.
 
 ### Naming
 
-Filters should match the dotted-path of the filtered attribute in the response.
+Filters should match the dotted-path of the filtered attribute in the response,
+to aid in discoverability and consistency.
 
-For example:
+Parameters must be hyphen-case (despite fields being camelCase in responses) to
+account for that fact that URLs are case-insensitive.
+
+For example, given:
 
 ```
 /3/teachers
 [ { id:
   , ...
   , school:
     { id:
+    , createdAt:
     , ...
     }
   }
 ]
 ```
 
-Here, a School filter would be `school.id`: `/3/teachers?school.id=1,2,3`.
+Here, a School filter would be `school.id` or `school.created-at`.
 
 ```
 /3/students
@@ -63,20 +89,6 @@ But here, it would be `schools.id`: `/3/students?schools.id=1,2,3`.
 If a filter exists that is not for an attribute present in the response, the
 name can be inferred by what it would look like if it were.
 
-### Semantics
-
-Prefer `IN` equality semantics.
-
-- Good: `{attribute}={value1},{value2},{value3},...`
-- Bad: `{attribute}={value}`
-
-This is because:
-
-- It's just as easy to support as direct equality
-- It reduces to the expected `EQUALS` semantics when given one value
-- We think we can get by with only this level "smart" filtering for a while and
-  defer more complexity in this area (e.g. "not", etc).
-
 ## Response fields
 
 - Always include `id`s