improved docs
This commit is contained in:
parent
cce5ff4ff7
commit
2ac2530c38
86
Readme.md
86
Readme.md
|
@ -1,14 +1,40 @@
|
|||
# Vikunja Web Handler
|
||||
|
||||
Vikunja was built with a maximum flexibility in mind while developing. To achive this, I built a set of easy-to-use
|
||||
functions and respective web handlers, all represented through interfaces.
|
||||
> When I started Vikunja, I started like everyone else, by writing a bunch of functions to do the logic and then a bunch of
|
||||
handler functions to parse the request data and call the implemented functions to do the logic and eventually return a dataset.
|
||||
After I implemented some functions, I've decided to save me a lot of hassle and put most of that "parse the request and call a
|
||||
processing function"-logic to a general interface to facilitate development and not having to have a lot of similar code all over the place.
|
||||
|
||||
This webhandler was built to be used in a REST-API, it takes and returns JSON, but can also be used in combination with own other handler
|
||||
implementations thus leading to much flexibility.
|
||||
|
||||
## Features
|
||||
|
||||
* Easy to use
|
||||
* Built for REST-APIs
|
||||
* Beautiful error handling built in
|
||||
* Manages rights
|
||||
* Pluggable authentication mechanisms
|
||||
|
||||
### Table of contents
|
||||
|
||||
* [CRUDable](#crudable)
|
||||
* [Rights](#rights)
|
||||
* [Handler Config](#handler-config)
|
||||
* [Auth](#auth)
|
||||
* [Logging](#logging)
|
||||
* [Full Example](#full-example)
|
||||
* [Preprocessing](#preprocessing)
|
||||
* [Pagination](#pagination)
|
||||
* [Search](#search)
|
||||
* [Standard web handler](#standard-web-handler)
|
||||
* [Errors](#errors)
|
||||
|
||||
In order to use the common web handler, the struct must implement the `web.CRUDable` and `web.Rights` interface.
|
||||
|
||||
## CRUDable
|
||||
|
||||
This interface defines methods to Create/Read/ReadAll/Update/Delete something. In order to use the common web
|
||||
handler, the struct must implement this and the `Rights` interface.
|
||||
|
||||
The interface is defined as followed:
|
||||
This interface defines methods to Create/Read/ReadAll/Update/Delete something. It is defined as followed:
|
||||
|
||||
```go
|
||||
type CRUDable interface {
|
||||
|
@ -36,7 +62,29 @@ All functions should behave like this, if they create or update something, they
|
|||
instance. The only exception is `ReadAll()` which returns an interface. Usually this is an array, because, well you cannot
|
||||
make an array of a set type (If you know a way to do this, don't hesitate to drop me a message).
|
||||
|
||||
### Handler Config
|
||||
## Rights
|
||||
|
||||
This interface defines methods to check for rights on structs. They accept an `Auth`-element as parameter and return a `bool`.
|
||||
|
||||
The interface is defined as followed:
|
||||
|
||||
```go
|
||||
type Rights interface {
|
||||
IsAdmin(Auth) bool
|
||||
CanWrite(Auth) bool
|
||||
CanRead(Auth) bool
|
||||
CanDelete(Auth) bool
|
||||
CanUpdate(Auth) bool
|
||||
CanCreate(Auth) bool
|
||||
}
|
||||
```
|
||||
|
||||
When using the standard web handler, all methods except `CanRead()` are called before their `CRUD` counterparts. `CanRead()`
|
||||
is called after `ReadOne()` was invoked as this would otherwise mean getting an object from the db to check if the user has the
|
||||
right to see it and then getting it again if thats the case. Calling the function afterwards means we only have to get the
|
||||
object once.
|
||||
|
||||
## Handler Config
|
||||
|
||||
The handler has some options which you can (and need to) configure.
|
||||
|
||||
|
@ -69,6 +117,8 @@ e.Use(func(next echo.HandlerFunc) echo.HandlerFunc {
|
|||
})
|
||||
```
|
||||
|
||||
## Preprocessing
|
||||
|
||||
### Pagination
|
||||
|
||||
When using the `ReadAll`-method, the third parameter contains the requested page. Your function should return only the number of results
|
||||
|
@ -92,28 +142,6 @@ As the logic for "give me everything" and "give me everything where the name con
|
|||
the function like this, in order to keep the places with mostly the same logic as few as possible. Also just adding `?s=query` to the url one already
|
||||
knows and uses is a lot more convenient.
|
||||
|
||||
## Rights
|
||||
|
||||
This interface defines methods to check for rights on structs. They accept an `Auth`-element as parameter and return a `bool`.
|
||||
|
||||
The interface is defined as followed:
|
||||
|
||||
```go
|
||||
type Rights interface {
|
||||
IsAdmin(Auth) bool
|
||||
CanWrite(Auth) bool
|
||||
CanRead(Auth) bool
|
||||
CanDelete(Auth) bool
|
||||
CanUpdate(Auth) bool
|
||||
CanCreate(Auth) bool
|
||||
}
|
||||
```
|
||||
|
||||
When using the standard web handler, all methods except `CanRead()` are called before their `CRUD` counterparts. `CanRead()`
|
||||
is called after `ReadOne()` was invoked as this would otherwise mean getting an object from the db to check if the user has the
|
||||
right to see it and then getting it again if thats the case. Calling the function afterwards means we only have to get the
|
||||
object once.
|
||||
|
||||
## Standard web handler
|
||||
|
||||
You can define routes for the standard web handler like so:
|
||||
|
|
Loading…
Reference in New Issue