diff options
author | Li Haoyi <haoyi.sg@gmail.com> | 2018-08-13 01:12:07 +0800 |
---|---|---|
committer | Li Haoyi <haoyi.sg@gmail.com> | 2018-08-13 01:12:07 +0800 |
commit | 974dcbe09830785f202f54959ae5397e9084f7a0 (patch) | |
tree | d127d2aff446b8c50debfae3823ebba7e2b457ea /docs/pages | |
parent | eb32d8d4a1e2bd50e5416fcfefd72dfe6da1a7bb (diff) | |
download | cask-974dcbe09830785f202f54959ae5397e9084f7a0.tar.gz cask-974dcbe09830785f202f54959ae5397e9084f7a0.tar.bz2 cask-974dcbe09830785f202f54959ae5397e9084f7a0.zip |
add docs on writing custom endpoints
Diffstat (limited to 'docs/pages')
-rw-r--r-- | docs/pages/1 - Cask: a Scala HTTP micro-framework .md | 37 |
1 files changed, 37 insertions, 0 deletions
diff --git a/docs/pages/1 - Cask: a Scala HTTP micro-framework .md b/docs/pages/1 - Cask: a Scala HTTP micro-framework .md index b41fbe6..db35e6b 100644 --- a/docs/pages/1 - Cask: a Scala HTTP micro-framework .md +++ b/docs/pages/1 - Cask: a Scala HTTP micro-framework .md @@ -243,6 +243,43 @@ This is convenient for cases where you want a set of decorators to apply broadly across your web application, and do not want to repeat them over and over at every single endpoint. +### Custom Endpoints + +$$$endpoints + +When you need more flexibility than decorators allow, you can define your own +custom `cask.Endpoint`s to replace the default set that Cask provides. This +allows you to + +- Change the expected return type of the annotated function, and how allows you + to that type gets processed: the above example trivially expects an allows you + to `Int` which becomes the status code, but you could make it e.g. + automatically serialize returned objects to JSON responses via your favorite + library, or serialize them to bytes via protobufs + +- Change where the first parameter list's params are taken from: `@cask.get` + takes them from query params, `@cask.postForm` takes them from the + form-encoded POST body, and you can write your own endpoint to take the params + from where-ever you like: perhaps from the request headers, or a protobuf- + encoded request body + +- Change how parameters are deserialized: e.g. `@cask.postJson` de-serializes + parameters using the [uPickle](https://github.com/lihaoyi/upickle) JSON + library, and your own custom endpoint could change that to use another library + like [Circe](https://github.com/circe/circe) or + [Jackson](https://github.com/FasterXML/jackson-module-scala) + +- DRY up common sets of decorators: if all your endpoint functions use the same + decorators, you can extract that functionality into a single `cask.Endpoint` + to do the job. + +Generally you should not be writing custom `cask.Endpoint`s every day, but if +you find yourself trying to standardize on a way of doing things across your web +application, it might make sense to write a custom endpoint decorator: to DRY +things up , separate business logic (inside the annotated function) from +plumbing (in the endpoint function and decorators), and enforcing a standard of +how endpoint functions are written. + ### Gzip & Deflated Responses |