Skip to content

Commit

Permalink
Remove info moved to RTD from README
Browse files Browse the repository at this point in the history
  • Loading branch information
hfaran committed Dec 21, 2013
1 parent fb270e5 commit dec0eca
Showing 1 changed file with 2 additions and 48 deletions.
50 changes: 2 additions & 48 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

## Overview

Tornado-JSON is a small extension of Tornado with the intent providing the tools necessary to get a JSON API up and running quickly. See `demos/helloworld/` for a quick example. RequestHandler Guidelines provided below should tell you why things are how they are.
Tornado-JSON is a small extension of Tornado with the intent providing the tools necessary to get a JSON API up and running quickly. See **[`demos/helloworld/`](https://github.com/hfaran/Tornado-JSON/tree/dev/demos/helloworld)** for a quick example. RequestHandler Guidelines provided below should tell you why things are how they are.

Some of the key features the included modules provide:

Expand All @@ -15,56 +15,10 @@ Some of the key features the included modules provide:
* *Automated Public API documentation* using schemas and provided descriptions
* Standardized output using the [JSend](http://labs.omniti.com/labs/jsend) specification

### **[Read the Docs for documentation!](http://tornado-json.readthedocs.org/en/latest/index.html#)**

<sub>*Warning: Tornado-JSON is still very much a work in progress. No guarantees on backwards-compatibility made, however, I try not to do that since, as a user, I hate breaking it at least as much as you. That being said, use it at your own risk.*</sub>

## Request Handler Guidelines

Create an `apid` dict in each RequestHandler as a class-level variable, i.e.,

```python
class ExampleHandler(APIHandler):
apid = {}
```

For each HTTP method you implement, add a corresponding entry in `apid`. The schemas must be valid JSON schemas; [readthedocs](https://python-jsonschema.readthedocs.org/en/latest/) for an example. Here is an example for POST:

```python
apid["post"] = {
"input_schema": ...,
"output_schema": ...,
"doc": ...,
}
```
`doc` is the **public** accompanying documentation that will be available on the wiki.

Use the `io_schema` decorator on methods which will automatically validate the request body and output against the schemas in `apid[method_name]`. Additionally, `return` the data from the request handler, rather than writing it back (the decorator will take care of that).

```python
class ExampleHandler(APIHandler):
@io_schema
def post(self, body):
...
return data
```

Use `utils.api_assert` to fail when some the client does not meet some API pre-condition/requirement, e.g., an invalid or incomplete request is made. When using an assertion is not suitable, `raise APIError( ... )`; don't use JSend `fail` directly.

```python
class ExampleHandler(APIHandler):
@io_schema
def post(self, body):
...
api_assert(condition, status_code, log_message=log_message)
```


## Documentation Generation

### Public API Usage Documentation

API Usage documentation is generated by the `tornado_json.api_doc_gen` module. The `api_doc_gen` method is run on startup so to generate documentation, simply run your app and the documentation will written to `API_Documentation.md`. in the current folder.


# Dependencies

Expand Down

0 comments on commit dec0eca

Please sign in to comment.