forked from boblefrag/python-rest-api-framework
-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Yohann Gabory
committed
Oct 14, 2013
1 parent
25d8cd4
commit 9b8c044
Showing
28 changed files
with
991 additions
and
96 deletions.
There are no files selected for viewing
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -12,6 +12,7 @@ Contents: | |
| :maxdepth: 2 | ||
|
|
||
| introduction | ||
| tutorial | ||
| datastore | ||
| controller | ||
| pagination | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,128 @@ | ||
| Tutorial building an adressebook API | ||
| ==================================== | ||
|
|
||
| First Step Building a user endpoint | ||
| ----------------------------------- | ||
|
|
||
| For this project we need users. Users will be helpfull for our adress | ||
| book and for our authentication process. | ||
|
|
||
| Users will be define with at least a first name and a last name. We | ||
| also need an unique identifier to retreive the user. | ||
|
|
||
| Define a model | ||
| ~~~~~~~~~~~~~~ | ||
|
|
||
| .. code-block:: python | ||
|
|
||
| from rest_api_framework import models | ||
|
|
||
| class UserModel(models.Model): | ||
|
|
||
| fields = [models.StringField(name="first_name", required=True), | ||
| models.StringField(name="last_name", required=True), | ||
| models.PkField(name="id", required=True) | ||
| ] | ||
|
|
||
| The use of required_true will ensure that a user without this field | ||
| cannot be created | ||
|
|
||
| Chose a DataStore | ||
| ~~~~~~~~~~~~~~~~~ | ||
|
|
||
| We also need a datastore to get a place where we can save our | ||
| users. For instance we will use a sqlite3 database. The | ||
| SQLiteDataStore is what we need | ||
|
|
||
| .. code-block:: python | ||
|
|
||
| from rest_api_framework.datastore import SQLiteDataStore | ||
|
|
||
| Chose a view | ||
| ~~~~~~~~~~~~ | ||
|
|
||
| We want results to be rendered as Json. We use the JsonResponse view | ||
| for that: | ||
|
|
||
| .. code-block:: python | ||
|
|
||
| from rest_api_framework.views import JsonResponse | ||
|
|
||
| Create The user endpoint | ||
| ~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
|
||
| To create an endpoint, we need a controller. This will manage our | ||
| endpoint in a RESTFUL fashion. | ||
|
|
||
| .. code-block:: python | ||
|
|
||
| from rest_api_framework.controllers import Controller | ||
|
|
||
| class UserEndPoint(Controller): | ||
| ressource = { | ||
| "ressource_name": "users", | ||
| "ressource": {"name": "adress_book.db", "table": "users"}, | ||
| "model": UserModel, | ||
| "datastore": SQLiteDataStore | ||
| } | ||
|
|
||
| controller = { | ||
| "list_verbs": ["GET", "POST"], | ||
| "unique_verbs": ["GET", "PUT", "DElETE"] | ||
| } | ||
|
|
||
| view = {"response_class": JsonResponse} | ||
|
|
||
| then we must run our application: | ||
|
|
||
| .. code-block:: python | ||
|
|
||
| if __name__ == '__main__': | ||
| from werkzeug.serving import run_simple | ||
| from rest_api_framework.controllers import WSGIDispatcher | ||
| app = WSGIDispatcher([UserEndPoint]) | ||
| run_simple('127.0.0.1', 5000, app, use_debugger=True, use_reloader=True) | ||
|
|
||
| Summary | ||
| ~~~~~~~ | ||
|
|
||
| So far, all of the code should look like this: | ||
|
|
||
| .. code-block:: python | ||
|
|
||
| from rest_api_framework import models | ||
| from rest_api_framework.datastore import SQLiteDataStore | ||
| from rest_api_framework.views import JsonResponse | ||
| from rest_api_framework.controllers import Controller | ||
|
|
||
|
|
||
| class UserModel(models.Model): | ||
|
|
||
| fields = [models.StringField(name="first_name", required=True), | ||
| models.StringField(name="last_name", required=True), | ||
| models.PkField(name="id", required=True) | ||
| ] | ||
|
|
||
|
|
||
| class UserEndPoint(Controller): | ||
| ressource = { | ||
| "ressource_name": "users", | ||
| "ressource": {"name": "adress_book.db", "table": "users"}, | ||
| "model": UserModel, | ||
| "datastore": SQLiteDataStore | ||
| } | ||
|
|
||
| controller = { | ||
| "list_verbs": ["GET", "POST"], | ||
| "unique_verbs": ["GET", "PUT", "DElETE"] | ||
| } | ||
|
|
||
| view = {"response_class": JsonResponse} | ||
|
|
||
| if __name__ == '__main__': | ||
| from werkzeug.serving import run_simple | ||
| from rest_api_framework.controllers import WSGIDispatcher | ||
| app = WSGIDispatcher([UserEndPoint]) | ||
| run_simple('127.0.0.1', 5000, app, use_debugger=True, use_reloader=True) | ||
|
|
||
| Next: :doc:`using_user_endpoint` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,62 @@ | ||
| Playing with the newly created endpoint | ||
| ======================================= | ||
|
|
||
| First you can check that your endpoint is up | ||
|
|
||
| .. code-block:: bash | ||
|
|
||
| curl -i "http://localhost:5000/users/" | ||
|
|
||
| HTTP/1.0 200 OK | ||
| Content-Type: application/json | ||
| Content-Length: 2 | ||
| Server: Werkzeug/0.8.3 Python/2.7.2 | ||
| Date: Mon, 14 Oct 2013 12:52:22 GMT | ||
|
|
||
| Your endpoint is responding but does not have any data. Let's add | ||
| some: | ||
|
|
||
| Create a user | ||
| ------------- | ||
|
|
||
| .. code-block:: bash | ||
|
|
||
| curl -i -H "Content-type: application/json" -X POST -d '{"first_name":"John", "last_name": "Doe"}' http://localhost:5000/users/ | ||
|
|
||
| HTTP/1.0 201 CREATED | ||
| Location: http://localhost:5000/users/1 | ||
| Content-Type: application/json | ||
| Content-Length: 0 | ||
| Server: Werkzeug/0.8.3 Python/2.7.2 | ||
| Date: Mon, 14 Oct 2013 13:00:13 GMT | ||
|
|
||
| Error handling | ||
| ~~~~~~~~~~~~~~ | ||
|
|
||
| If you don't provide a last_name, the API will raise a BAD REQUEST | ||
| explaining your error: | ||
|
|
||
| .. code-block:: bash | ||
|
|
||
| curl -i -H "Content-type: application/json" -X POST -d '{"first_name":"John"}' http://localhost:5000/users/ | ||
|
|
||
| HTTP/1.0 400 BAD REQUEST | ||
| Content-Type: application/json | ||
| Content-Length: 62 | ||
| Server: Werkzeug/0.8.3 Python/2.7.2 | ||
| Date: Mon, 14 Oct 2013 13:21:10 GMT | ||
|
|
||
| {"error": "last_name is missing. Cannot create the ressource"} | ||
|
|
||
| The same apply if you dont give coherent data: | ||
|
|
||
| .. code-block:: bash | ||
|
|
||
| curl -i -H "Content-type: application/json" -X POST -d '{"first_name":45, "last_name": "Doe"}' http://localhost:5000/users/ | ||
|
|
||
| HTTP/1.0 400 BAD REQUEST | ||
| Content-Type: application/json | ||
| Content-Length: 41 | ||
| Server: Werkzeug/0.8.3 Python/2.7.2 | ||
| Date: Mon, 14 Oct 2013 13:24:53 GMT | ||
| {"error": "first_name does not validate"} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Binary file not shown.
Oops, something went wrong.