Update README with API documentation

Author: abrandemuehl

README.md

@@ -1,9 +1,46 @@
-# Merch Embedded 
-
+# Merch Embedded
 
 [![Join the chat at https://gitter.im/acm-uiuc/merch-development](https://badges.gitter.im/acm-uiuc/merch-development.svg)](https://gitter.im/acm-uiuc/merch-development?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 
-Possible information sources:
+
+This repository contains all of the code related to controlling the underlying merch hardware (the vending machine).
+Merch runs an embedded webserver that can be accessed at merch.acm.illinois.edu.
+
+## API
+
+Every request through the API has a token in the header that is unique to groot.
+This way, only groot can make requests to vend things.
+The token is stored in the request header.
+
+### Vend a location
+To vend a list of items, POST a request to `/vend`.
+The request is of the form
+```json
+{
+    "transaction_id": 1,
+    "items": ["A1", "B2", "C3"]
+}
+```
+
+The machine will respond with
+```json
+{
+    "transaction_id": 1,
+    "items": [
+        {"location": "A1", "error": null},
+        {"location": "B2", "error": "some sort of error"},
+        {"location": "C3", "error": null},
+
+    ]
+}
+```
+
+The errors that can take place while vending are currently:
+* `"Invalid location"`
+
+
+## Some related datasheets
+
 [http://bajavending.com/Manual-de-Operacion-BevMax.pdf](http://bajavending.com/Manual-de-Operacion-BevMax.pdf)
 * Has the right picture of the main controller board, no programming information though
 
@@ -18,15 +55,15 @@ has some useful info about what commands are sent
 
 ## License
 
-This project is licensed under the University of Illinois/NCSA Open Source License. For a full copy of this license take a look at the LICENSE file. 
+This project is licensed under the University of Illinois/NCSA Open Source License. For a full copy of this license take a look at the LICENSE file.
 
-When contributing new files to this project, preappend the following header to the file as a comment: 
+When contributing new files to this project, preappend the following header to the file as a comment:
 
 ```
 Copyright © 2017, ACM@UIUC
 
-This file is part of the Merch Project.  
- 
-The Merch Project is open source software, released under the University of Illinois/NCSA Open Source License. 
+This file is part of the Merch Project.
+
+The Merch Project is open source software, released under the University of Illinois/NCSA Open Source License.
 You should have received a copy of this license in a file with the distribution.
 ```