Skip to content

Commit

Permalink
feat(136): improve wording around declarative clients (#244)
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
toumorokoshi authored Nov 14, 2024
1 parent 53da5a2 commit eff5366
Showing 1 changed file with 7 additions and 8 deletions.
15 changes: 7 additions & 8 deletions aep/general/0136/aep.md.j2
Original file line number Diff line number Diff line change
Expand Up @@ -119,16 +119,15 @@ permanent effect on data within the API.
collection). For example, `:translateText` is preferable to `text:translate`.
- Stateless methods **must** use `POST` if they involve billing.

### Declarative-friendly resources
### Usage in declarative clients

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

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

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

0 comments on commit eff5366

Please sign in to comment.