Skip to content

Commit eff5366

Browse files
authored
feat(136): improve wording around declarative clients (#244)
The existing guidance was a big vague on the impact of a custom method in a declarative client. This attempts to clarify the impact of making that choice.
1 parent 53da5a2 commit eff5366

File tree

1 file changed

+7
-8
lines changed

1 file changed

+7
-8
lines changed

aep/general/0136/aep.md.j2

+7-8
Original file line numberDiff line numberDiff line change
@@ -119,16 +119,15 @@ permanent effect on data within the API.
119119
collection). For example, `:translateText` is preferable to `text:translate`.
120120
- Stateless methods **must** use `POST` if they involve billing.
121121

122-
### Declarative-friendly resources
122+
### Usage in declarative clients
123123

124-
Declarative-friendly resources usually **should not** employ custom methods
125-
(except specific declarative-friendly custom methods discussed in other AEPs),
126-
because declarative-friendly tools are unable to automatically determine what
127-
to do with them.
124+
APIs **should not** employ custom methods for functionality that is intended to
125+
be used in a [declarative client](/3#declarative-clients). Declarative clients
126+
use create,read,update,and delete operations to apply desired state, and
127+
integration of custom methods is manual and results in client-side complexity
128+
around state management to determine when the custom method should be invoked.
128129

129-
An exception to this is for rarely-used, fundamentally imperative operations,
130-
such as a `Move`, `Rename`, or `Restart` operation, for which there would not
131-
be an expectation of declarative support.
130+
AEP's supported declarative clients cannot support custom methods.
132131

133132
<!-- prettier-ignore-start -->
134133
[rfc 5789]: https://datatracker.ietf.org/doc/html/rfc5789

0 commit comments

Comments
 (0)