mirror of
https://github.com/Kong/insomnia.git
synced 2026-07-30 17:26:28 -04:00
34 lines
1.2 KiB
Markdown
34 lines
1.2 KiB
Markdown
# Service API conventions
|
|
|
|
## Generic database-shaped APIs
|
|
|
|
Use these names when a service intentionally exposes the matching database operation for its model type:
|
|
|
|
- `list(query?, sort?, limit?)` -> `database.find(modelType, query, sort, limit)`
|
|
- `get(query?, sort?)` -> `database.findOne(modelType, query, sort)`
|
|
- `count(query?)` -> `database.count(modelType, query)`
|
|
|
|
Use `getById(id)` for the common `_id` lookup. Do not use `get(id)` for id lookup when `get` is the generic `findOne` API.
|
|
|
|
## Mutation APIs
|
|
|
|
Use existing model mutation names unless the method represents a broader workflow:
|
|
|
|
- `create(patch?)`
|
|
- `update(docOrId, patch)`
|
|
- `remove(docOrId)`
|
|
|
|
## Named query helpers
|
|
|
|
Add named helpers only when there is an actual caller or repeated business need. Do not pre-create parallel helper families such as `countBy...` unless they are used.
|
|
|
|
Name helpers by the filter they represent:
|
|
|
|
- `listByRemoteId(remoteId)`
|
|
- `listByGitRepositoryIds(gitRepositoryIds)`
|
|
- `listByOrganizationIds(organizationIds)`
|
|
|
|
When one helper must support both one id and many ids, prefer one plural API with `string | string[]` over separate singular and plural methods.
|
|
|
|
Workflow methods should be named by business intent, not database mechanics.
|