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 Web Handler
|
||||||
|
|
||||||
Vikunja was built with a maximum flexibility in mind while developing. To achive this, I built a set of easy-to-use
|
> When I started Vikunja, I started like everyone else, by writing a bunch of functions to do the logic and then a bunch of
|
||||||
functions and respective web handlers, all represented through interfaces.
|
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
|
## CRUDable
|
||||||
|
|
||||||
This interface defines methods to Create/Read/ReadAll/Update/Delete something. In order to use the common web
|
This interface defines methods to Create/Read/ReadAll/Update/Delete something. It is defined as followed:
|
||||||
handler, the struct must implement this and the `Rights` interface.
|
|
||||||
|
|
||||||
The interface is defined as followed:
|
|
||||||
|
|
||||||
```go
|
```go
|
||||||
type CRUDable interface {
|
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
|
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).
|
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.
|
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
|
### Pagination
|
||||||
|
|
||||||
When using the `ReadAll`-method, the third parameter contains the requested page. Your function should return only the number of results
|
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
|
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.
|
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
|
## Standard web handler
|
||||||
|
|
||||||
You can define routes for the standard web handler like so:
|
You can define routes for the standard web handler like so:
|
||||||
|
|
Loading…
Reference in New Issue
Block a user