diff --git a/node.js/cds-serve.md b/node.js/cds-serve.md index abb234700..4c418ec8c 100644 --- a/node.js/cds-serve.md +++ b/node.js/cds-serve.md @@ -208,7 +208,7 @@ srv/cat-service.js #> service implementation used by default For each service served at a certain protocol, the framework registers a configurable set of express middlewares by default like so: ```js -app.use (cds.middlewares.before, protocol_adapter) +app.use (cds.middlewares.before, protocol_adapter, cds.middlewares.after) ``` The standard set of middlewares uses the following order: @@ -222,6 +222,16 @@ cds.middlewares.before = [ ] ``` +```js +cds.middlewares.after = [ + cds_error_handler(), // provides final error handling +] +``` + +::: tip Custom error middleware before `cds_error_handler` +To invoke a custom error middleware successfully, you must register it _before_ the built-in `cds_error_handler`. You can achieve that, for example, by adding the middleware using `cds.middlewares.after.unshift()`. +::: + ::: warning _Be aware of the interdependencies of middlewares_ _ctx_model_ requires that _cds.context_ middleware has run before. _ctx_auth_ requires that _authentication_ has run before. @@ -400,6 +410,31 @@ service CatalogService {} Be aware that using an absolute path will disallow serving the service at multiple protocols. +### PATCH vs. PUT vs. Replace + +The HTTP method `PATCH` is meant for partial modification of an _existing resource_. +`PUT`, on the other hand, is meant for ensuring a resource exists +That is, if it doesn't yet exists, it gets created. +If it does exist, it gets updated to reflect the request's content. + +This content, however, may be incomplete. +By default, the values for not listed keys are not touched. +The rationale being that default values are known and clients have the option to send full representations, if necessary. + +The following table shows the Node.js runtime's configuration options and their respective default value: + +| Flag | Behavior | Default | +|----------------------------------------------|------------------------------------------|---------| +| cds.runtime.patch_as_upsert = false | Create resource if it does not yet exist | false | +| cds.runtime.put_as_upsert = true | Create resource if it does not yet exist | true | +| cds.runtime.put_as_replace = false | Payload is enriched with default values | false | + +### Base Protocol Adapter + +All CAP-own protocol adapters extend a base protocol adapter that mounts the following middlewares: +1. `http_log`: log all incoming requests +2. `requires_check`: check the required roles for the respective service + ### Custom Protocol Adapter Similar to the configuration of the GraphQL Adapter, you can plug in your own protocol.