Commit 794a8b69 authored by Nicolas Lenz's avatar Nicolas Lenz

API Documentation

parent 8e610c91
## Haskell Setup
# WMS Server
1. If you haven't already, [install Stack](https://haskell-lang.org/get-started)
* On POSIX systems, this is usually `curl -sSL https://get.haskellstack.org/ | sh`
2. Install the `yesod` command line tool: `stack install yesod-bin --install-ghc`
3. Build libraries: `stack build`
## Info
This is the server application for my Warehouse Management System. It is meant to be used with the [fitting voice-controlled Android app](https://git.eisfunke.com/software/wms-app).
This is written in Haskell, using Yesod as web framework and stack as build tool.
If you have trouble, refer to the [Yesod Quickstart guide](https://www.yesodweb.com/page/quickstart) for additional detail.
As it has users with passwords, it should *only* be used through a secure HTTPS connection. Locally, the passwords are of course saved securely encrypted (hashed and salted using Argon2, that is).
## Development
Basic setup instructions can be found at the end of this file.
Start a development server with:
```
stack exec -- yesod devel
```
## API
As your code changes, your site will be automatically recompiled and redeployed to localhost.
These are the addresses this server serves:
## Tests
- `/container/#Int`
- `GET`: Gets information about the locations of a container as JSON list.
Example: `/container/123`
```
[
{
"amount": 3,
"location": "A1"
},
{
"amount": 12,
"location": "B3"
}
]
```
- `PUT`: Sets the location information for a container. The request must contain a body formatted like the output of a GET, see above.
- `/container`
- `GET`: Gets information about all known containers as JSON list.
Example:
```
[
{
"container": 123,
"allocations": [
{
"amount": 3,
"location": "A1"
},
{
"amount": 12,
"location": "B3"
}
]
}
]
```
- /containers.csv
- `GET`: Returns a CSV file containing data on all known containers.
- /location/#Text
- `GET`: Gets information about the containers stored in a location.
Example:
```
[
{
"amount": 12,
"container": 123
}
]
```
- `PUT`: Sets the information about a location. The request body must be formatted like the output of a GET, see above.
- `/location`
- `GET`: Gets information about all locations.
Example:
```
[
{
"location": "K23",
"allocations": [
{
"amount": 42,
"container": 456
}
]
}
```
```
stack test --flag wms-server:library-only --flag wms-server:dev
```
- `/add`
- `POST`: Allows to add specific containers easily. Format the body like this:
```
{
"amount": 10,
"container": 42,
"location": "J11"
}
```
- `/log`
- `GET`: Returns the action log.
Example:
```
[
{
"time": "2019-08-14T13:23:53.545977086Z",
"action": "Put away",
"details": "Put 12 of 123 to J1-23"
}
]
```
(Because `yesod devel` passes the `library-only` and `dev` flags, matching those flags means you don't need to recompile between tests and development, and it disables optimization to speed up your test compile times).
- `/user/#Text`
- `PUT`: Sets (that is, adds or changes password) a user. Format the body like this:
```
{
"password": "securePassword123"
}
```
- `DELETE`: Deletes the user.
- `/user`
- `GET`: Gets names of all known users.
Example: `/user/peter`
```
["testuser1", "testuser2"]
```
- `POST`: Allows to post user data using HTML forms and simple key value pairs. Needs a key "request" containing either "put", which will set a user and needs keys "username" and "password" to be set, or "delete" which needs only the key "username" to be set.
- `/control`
- `GET`: A control panel for user data.
## Documentation
- `/`
- `GET`: Home page, shows all known containers and has links to the control panel and CSV file.
* Read the [Yesod Book](https://www.yesodweb.com/book) online for free
* Check [Stackage](http://stackage.org/) for documentation on the packages in your LTS Haskell version, or [search it using Hoogle](https://www.stackage.org/lts/hoogle?q=). Tip: Your LTS version is in your `stack.yaml` file.
* For local documentation, use:
* `stack haddock --open` to generate Haddock documentation for your dependencies, and open that documentation in a browser
* `stack hoogle <function, module or type signature>` to generate a Hoogle database and search for your query
* The [Yesod cookbook](https://github.com/yesodweb/yesod-cookbook) has sample code for various needs
## Getting Help
## Setup
1. If you haven't already, [install Stack](https://haskell-lang.org/get-started)
* On POSIX systems, this is usually `curl -sSL https://get.haskellstack.org/ | sh`
2. Build: `stack build`
3. Start: `stack exec wms-server`
* Ask questions on [Stack Overflow, using the Yesod or Haskell tags](https://stackoverflow.com/questions/tagged/yesod+haskell)
* Ask the [Yesod Google Group](https://groups.google.com/forum/#!forum/yesodweb)
* There are several chatrooms you can ask for help:
* For IRC, try Freenode#yesod and Freenode#haskell
* [Functional Programming Slack](https://fpchat-invite.herokuapp.com/), in the #haskell, #haskell-beginners, or #yesod channels.
A user can be added with `stack exec wms-server-ctl add-user USERNAME`. It will ask for a password.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment