Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Document a bit more about query parameters #65

Merged
merged 3 commits into from
Sep 16, 2021
Merged

Document a bit more about query parameters #65

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0c1cd3a
Tweak phrasing and formatting in API docs
pbrisbin Sep 15, 2021
48e0287
Parameters must be hyphen-case, and why
pbrisbin Sep 15, 2021
cc7134e
Describe operation suffixes
pbrisbin Sep 15, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 14 additions & 14 deletions haskell-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,21 @@ Bad:
- `/3/teachers/:id/students`
- `/3/schools/:id/teachers/:id/students`

### Operations

For complex filtering, follow an "operation suffix" syntax,

Good:

- `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

Expand Down Expand Up @@ -75,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:
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I didn't think this justification was super valuable, so once I mentioned the "behave like [in]" in the new section, I figured we could drop all this. If anyon disagrees, I can move this content up there instead.


- 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
Expand Down