From 152c385f4de37558fe4e522abad5b97f0cf7ddce Mon Sep 17 00:00:00 2001 From: Sébastien Piquemal Date: Wed, 25 Jan 2012 00:11:54 +0200 Subject: enhanced request how-to + example --- docs/howto/requestmixin.rst | 76 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 76 insertions(+) create mode 100644 docs/howto/requestmixin.rst (limited to 'docs/howto') diff --git a/docs/howto/requestmixin.rst b/docs/howto/requestmixin.rst new file mode 100644 index 00000000..a00fdad0 --- /dev/null +++ b/docs/howto/requestmixin.rst @@ -0,0 +1,76 @@ +Using the enhanced request in all your views +============================================== + +This example shows how you can use Django REST framework's enhanced `request` in your own views, without having to use the full-blown :class:`views.View` class. + +What can it do for you ? Mostly, it will take care of parsing the request's content, and handling equally all HTTP methods ... + +Before +-------- + +In order to support `JSON` or other serial formats, you might have parsed manually the request's content with something like : :: + + class MyView(View): + + def put(self, request, *args, **kwargs): + content_type = request.META['CONTENT_TYPE'] + if (content_type == 'application/json'): + raw_data = request.read() + parsed_data = json.loads(raw_data) + + # PLUS as many `elif` as formats you wish to support ... + + # then do stuff with your data : + self.do_stuff(parsed_data['bla'], parsed_data['hoho']) + + # and finally respond something + +... and you were unhappy because this looks hackish. + +Also, you might have tried uploading files with a PUT request - *and given up* since that's complicated to achieve even with Django 1.3. + + +After +------ + +All the dirty `Content-type` checking and content reading and parsing is done for you, and you only need to do the following : :: + + class MyView(MyBaseViewUsingEnhancedRequest): + + def put(self, request, *args, **kwargs): + self.do_stuff(request.DATA['bla'], request.DATA['hoho']) + # and finally respond something + +So the parsed content is magically available as `.DATA` on the `request` object. + +Also, if you uploaded files, they are available as `.FILES`, like with a normal POST request. + +.. note:: Note that all the above is also valid for a POST request. + + +How to add it to your custom views ? +-------------------------------------- + +Now that you're convinced you need to use the enhanced request object, here is how you can add it to all your custom views : :: + + from django.views.generic.base import View + + from djangorestframework.mixins import RequestMixin + from djangorestframework import parsers + + + class MyBaseViewUsingEnhancedRequest(RequestMixin, View): + """ + Base view enabling the usage of enhanced requests with user defined views. + """ + + parsers = parsers.DEFAULT_PARSERS + + def dispatch(self, request, *args, **kwargs): + self.request = request + request = self.get_request() + return super(MyBaseViewUsingEnhancedRequest, self).dispatch(request, *args, **kwargs) + +And then, use this class as a base for all your custom views. + +.. note:: you can also check the request example. -- cgit v1.2.3 From 6963fd3623ee217fe489abb25f0ffa8c0781e4cd Mon Sep 17 00:00:00 2001 From: Sébastien Piquemal Date: Tue, 7 Feb 2012 16:22:14 +0200 Subject: some docs for Request/Response/mixins --- docs/howto/requestmixin.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) (limited to 'docs/howto') diff --git a/docs/howto/requestmixin.rst b/docs/howto/requestmixin.rst index a00fdad0..c0aadb3f 100644 --- a/docs/howto/requestmixin.rst +++ b/docs/howto/requestmixin.rst @@ -1,7 +1,7 @@ Using the enhanced request in all your views ============================================== -This example shows how you can use Django REST framework's enhanced `request` in your own views, without having to use the full-blown :class:`views.View` class. +This example shows how you can use Django REST framework's enhanced `request` - :class:`request.Request` - in your own views, without having to use the full-blown :class:`views.View` class. What can it do for you ? Mostly, it will take care of parsing the request's content, and handling equally all HTTP methods ... @@ -64,13 +64,12 @@ Now that you're convinced you need to use the enhanced request object, here is h Base view enabling the usage of enhanced requests with user defined views. """ - parsers = parsers.DEFAULT_PARSERS + parser_classes = parsers.DEFAULT_PARSERS def dispatch(self, request, *args, **kwargs): - self.request = request - request = self.get_request() + request = self.prepare_request(request) return super(MyBaseViewUsingEnhancedRequest, self).dispatch(request, *args, **kwargs) And then, use this class as a base for all your custom views. -.. note:: you can also check the request example. +.. note:: you can see this live in the examples. -- cgit v1.2.3 From af9e4f69d732cc643d6ec7ae13d4a19ac0332d44 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Tue, 21 Feb 2012 20:12:14 +0000 Subject: Merging master into develop --- docs/howto/reverse.rst | 47 ++++++++++++++++++++++++++++++++++++ docs/howto/setup.rst | 65 ++++++++++++++++++++++++++++++++------------------ 2 files changed, 89 insertions(+), 23 deletions(-) create mode 100644 docs/howto/reverse.rst (limited to 'docs/howto') diff --git a/docs/howto/reverse.rst b/docs/howto/reverse.rst new file mode 100644 index 00000000..e4efbbca --- /dev/null +++ b/docs/howto/reverse.rst @@ -0,0 +1,47 @@ +Returning URIs from your Web APIs +================================= + + "The central feature that distinguishes the REST architectural style from + other network-based styles is its emphasis on a uniform interface between + components." + + -- Roy Fielding, Architectural Styles and the Design of Network-based Software Architectures + +As a rule, it's probably better practice to return absolute URIs from you web APIs, e.g. "http://example.com/foobar", rather than returning relative URIs, e.g. "/foobar". + +The advantages of doing so are: + +* It's more explicit. +* It leaves less work for your API clients. +* There's no ambiguity about the meaning of the string when it's found in representations such as JSON that do not have a native URI type. +* It allows us to easily do things like markup HTML representations with hyperlinks. + +Django REST framework provides two utility functions to make it simpler to return absolute URIs from your Web API. + +There's no requirement for you to use them, but if you do then the self-describing API will be able to automatically hyperlink its output for you, which makes browsing the API much easier. + +reverse(viewname, request, ...) +------------------------------- + +The :py:func:`~utils.reverse` function has the same behavior as :py:func:`django.core.urlresolvers.reverse` [1]_, except that it takes a request object and returns a fully qualified URL, using the request to determine the host and port:: + + from djangorestframework.utils import reverse + from djangorestframework.views import View + + class MyView(View): + def get(self, request): + context = { + 'url': reverse('year-summary', request, args=[1945]) + } + + return Response(context) + +reverse_lazy(viewname, request, ...) +------------------------------------ + +The :py:func:`~utils.reverse_lazy` function has the same behavior as :py:func:`django.core.urlresolvers.reverse_lazy` [2]_, except that it takes a request object and returns a fully qualified URL, using the request to determine the host and port. + +.. rubric:: Footnotes + +.. [1] https://docs.djangoproject.com/en/dev/topics/http/urls/#reverse +.. [2] https://docs.djangoproject.com/en/dev/topics/http/urls/#reverse-lazy diff --git a/docs/howto/setup.rst b/docs/howto/setup.rst index 22f98f0c..0af1449c 100644 --- a/docs/howto/setup.rst +++ b/docs/howto/setup.rst @@ -3,45 +3,58 @@ Setup ===== -Installing into site-packages ------------------------------ +Templates +--------- -If you need to manually install Django REST framework to your ``site-packages`` directory, run the ``setup.py`` script:: +Django REST framework uses a few templates for the HTML and plain text +documenting renderers. You'll need to ensure ``TEMPLATE_LOADERS`` setting +contains ``'django.template.loaders.app_directories.Loader'``. +This will already be the case by default. - python setup.py install +You may customize the templates by creating a new template called +``djangorestframework/api.html`` in your project, which should extend +``djangorestframework/base.html`` and override the appropriate +block tags. For example:: -Template Loaders ----------------- + {% extends "djangorestframework/base.html" %} -Django REST framework uses a few templates for the HTML and plain text documenting renderers. + {% block title %}My API{% endblock %} -* Ensure ``TEMPLATE_LOADERS`` setting contains ``'django.template.loaders.app_directories.Loader'``. + {% block branding %} +

My API

+ {% endblock %} -This will be the case by default so you shouldn't normally need to do anything here. -Admin Styling -------------- +Styling +------- -Django REST framework uses the admin media for styling. When running using Django's testserver this is automatically served for you, -but once you move onto a production server, you'll want to make sure you serve the admin media separately, exactly as you would do -`if using the Django admin `_. +Django REST framework requires `django.contrib.staticfiles`_ to serve it's css. +If you're using Django 1.2 you'll need to use the seperate +`django-staticfiles`_ package instead. + +You can override the styling by creating a file in your top-level static +directory named ``djangorestframework/css/style.css`` -* Ensure that the ``ADMIN_MEDIA_PREFIX`` is set appropriately and that you are serving the admin media. - (Django's testserver will automatically serve the admin media for you) Markdown -------- -The Python `markdown library `_ is not required but comes recommended. +`Python markdown`_ is not required but comes recommended. + +If markdown is installed your :class:`.Resource` descriptions can include +`markdown formatting`_ which will be rendered by the self-documenting API. + +YAML +---- + +YAML support is optional, and requires `PyYAML`_. -If markdown is installed your :class:`.Resource` descriptions can include `markdown style formatting -`_ which will be rendered by the HTML documenting renderer. -login/logout ---------------------------------- +Login / Logout +-------------- -Django REST framework comes with a few views that can be useful including an api -login and logout views:: +Django REST framework includes login and logout views that are useful if +you're using the self-documenting API:: from django.conf.urls.defaults import patterns @@ -51,3 +64,9 @@ login and logout views:: (r'^accounts/logout/$', 'api_logout'), ) +.. _django.contrib.staticfiles: https://docs.djangoproject.com/en/dev/ref/contrib/staticfiles/ +.. _django-staticfiles: http://pypi.python.org/pypi/django-staticfiles/ +.. _URLObject: http://pypi.python.org/pypi/URLObject/ +.. _Python markdown: http://www.freewisdom.org/projects/python-markdown/ +.. _markdown formatting: http://daringfireball.net/projects/markdown/syntax +.. _PyYAML: http://pypi.python.org/pypi/PyYAML \ No newline at end of file -- cgit v1.2.3 From 5fd4c639d7c64572dd07dc31dcd627bed9469b05 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Tue, 21 Feb 2012 20:57:36 +0000 Subject: Merge master into develop --- docs/howto/reverse.rst | 18 +++++------------- 1 file changed, 5 insertions(+), 13 deletions(-) (limited to 'docs/howto') diff --git a/docs/howto/reverse.rst b/docs/howto/reverse.rst index e4efbbca..73b8fa4d 100644 --- a/docs/howto/reverse.rst +++ b/docs/howto/reverse.rst @@ -1,12 +1,6 @@ Returning URIs from your Web APIs ================================= - "The central feature that distinguishes the REST architectural style from - other network-based styles is its emphasis on a uniform interface between - components." - - -- Roy Fielding, Architectural Styles and the Design of Network-based Software Architectures - As a rule, it's probably better practice to return absolute URIs from you web APIs, e.g. "http://example.com/foobar", rather than returning relative URIs, e.g. "/foobar". The advantages of doing so are: @@ -23,9 +17,9 @@ There's no requirement for you to use them, but if you do then the self-describi reverse(viewname, request, ...) ------------------------------- -The :py:func:`~utils.reverse` function has the same behavior as :py:func:`django.core.urlresolvers.reverse` [1]_, except that it takes a request object and returns a fully qualified URL, using the request to determine the host and port:: +The :py:func:`~reverse.reverse` function has the same behavior as `django.core.urlresolvers.reverse`_, except that it takes a request object and returns a fully qualified URL, using the request to determine the host and port:: - from djangorestframework.utils import reverse + from djangorestframework.reverse import reverse from djangorestframework.views import View class MyView(View): @@ -39,9 +33,7 @@ The :py:func:`~utils.reverse` function has the same behavior as :py:func:`django reverse_lazy(viewname, request, ...) ------------------------------------ -The :py:func:`~utils.reverse_lazy` function has the same behavior as :py:func:`django.core.urlresolvers.reverse_lazy` [2]_, except that it takes a request object and returns a fully qualified URL, using the request to determine the host and port. - -.. rubric:: Footnotes +The :py:func:`~reverse.reverse_lazy` function has the same behavior as `django.core.urlresolvers.reverse_lazy`_, except that it takes a request object and returns a fully qualified URL, using the request to determine the host and port. -.. [1] https://docs.djangoproject.com/en/dev/topics/http/urls/#reverse -.. [2] https://docs.djangoproject.com/en/dev/topics/http/urls/#reverse-lazy +.. _django.core.urlresolvers.reverse: https://docs.djangoproject.com/en/dev/topics/http/urls/#reverse +.. _django.core.urlresolvers.reverse_lazy: https://docs.djangoproject.com/en/dev/topics/http/urls/#reverse-lazy -- cgit v1.2.3 From 1cde31c86d9423e9b7a7409c2ef2ba7c0500e47f Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Sat, 25 Feb 2012 18:45:17 +0000 Subject: Massive merge --- docs/howto/setup.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) (limited to 'docs/howto') diff --git a/docs/howto/setup.rst b/docs/howto/setup.rst index 0af1449c..081c6412 100644 --- a/docs/howto/setup.rst +++ b/docs/howto/setup.rst @@ -49,20 +49,20 @@ YAML YAML support is optional, and requires `PyYAML`_. - Login / Logout -------------- -Django REST framework includes login and logout views that are useful if -you're using the self-documenting API:: +Django REST framework includes login and logout views that are needed if +you're using the self-documenting API. + +Make sure you include the following in your `urlconf`:: - from django.conf.urls.defaults import patterns + from django.conf.urls.defaults import patterns, url - urlpatterns = patterns('djangorestframework.views', - # Add your resources here - (r'^accounts/login/$', 'api_login'), - (r'^accounts/logout/$', 'api_logout'), - ) + urlpatterns = patterns('', + ... + url(r'^restframework', include('djangorestframework.urls', namespace='djangorestframework')) + ) .. _django.contrib.staticfiles: https://docs.djangoproject.com/en/dev/ref/contrib/staticfiles/ .. _django-staticfiles: http://pypi.python.org/pypi/django-staticfiles/ -- cgit v1.2.3 From 578017e01d1da4746ae0045268043cfd74d41b42 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Wed, 29 Aug 2012 20:57:37 +0100 Subject: New docs --- docs/howto/alternativeframeworks.rst | 35 ----------------- docs/howto/mixin.rst | 30 --------------- docs/howto/requestmixin.rst | 75 ------------------------------------ docs/howto/reverse.rst | 39 ------------------- docs/howto/setup.rst | 73 ----------------------------------- docs/howto/usingcurl.rst | 30 --------------- docs/howto/usingurllib2.rst | 39 ------------------- 7 files changed, 321 deletions(-) delete mode 100644 docs/howto/alternativeframeworks.rst delete mode 100644 docs/howto/mixin.rst delete mode 100644 docs/howto/requestmixin.rst delete mode 100644 docs/howto/reverse.rst delete mode 100644 docs/howto/setup.rst delete mode 100644 docs/howto/usingcurl.rst delete mode 100644 docs/howto/usingurllib2.rst (limited to 'docs/howto') diff --git a/docs/howto/alternativeframeworks.rst b/docs/howto/alternativeframeworks.rst deleted file mode 100644 index dc8d1ea6..00000000 --- a/docs/howto/alternativeframeworks.rst +++ /dev/null @@ -1,35 +0,0 @@ -Alternative frameworks & Why Django REST framework -================================================== - -Alternative frameworks ----------------------- - -There are a number of alternative REST frameworks for Django: - -* `django-piston `_ is very mature, and has a large community behind it. This project was originally based on piston code in parts. -* `django-tasypie `_ is also very good, and has a very active and helpful developer community and maintainers. -* Other interesting projects include `dagny `_ and `dj-webmachine `_ - - -Why use Django REST framework? ------------------------------- - -The big benefits of using Django REST framework come down to: - -1. It's based on Django's class based views, which makes it simple, modular, and future-proof. -2. It stays as close as possible to Django idioms and language throughout. -3. The browse-able API makes working with the APIs extremely quick and easy. - - -Why was this project created? ------------------------------ - -For me the browse-able API is the most important aspect of Django REST framework. - -I wanted to show that Web APIs could easily be made Web browse-able, -and demonstrate how much better browse-able Web APIs are to work with. - -Being able to navigate and use a Web API directly in the browser is a huge win over only having command line and programmatic -access to the API. It enables the API to be properly self-describing, and it makes it much much quicker and easier to work with. -There's no fundamental reason why the Web APIs we're creating shouldn't be able to render to HTML as well as JSON/XML/whatever, -and I really think that more Web API frameworks *in whatever language* ought to be taking a similar approach. diff --git a/docs/howto/mixin.rst b/docs/howto/mixin.rst deleted file mode 100644 index 1a84f2ad..00000000 --- a/docs/howto/mixin.rst +++ /dev/null @@ -1,30 +0,0 @@ -Using Django REST framework Mixin classes -========================================= - -This example demonstrates creating a REST API **without** using Django REST framework's :class:`.Resource` or :class:`.ModelResource`, but instead using Django's :class:`View` class, and adding the :class:`ResponseMixin` class to provide full HTTP Accept header content negotiation, -a browseable Web API, and much of the other goodness that Django REST framework gives you for free. - -.. note:: - - A live sandbox instance of this API is available for testing: - - * http://rest.ep.io/mixin/ - - You can browse the API using a web browser, or from the command line:: - - curl -X GET http://rest.ep.io/mixin/ - - -URL configuration ------------------ - -Everything we need for this example can go straight into the URL conf... - -``urls.py`` - -.. include:: ../../examples/mixin/urls.py - :literal: - -That's it. Auto-magically our API now supports multiple output formats, specified either by using -standard HTTP Accept header content negotiation, or by using the `&_accept=application/json` style parameter overrides. -We even get a nice HTML view which can be used to self-document our API. diff --git a/docs/howto/requestmixin.rst b/docs/howto/requestmixin.rst deleted file mode 100644 index c0aadb3f..00000000 --- a/docs/howto/requestmixin.rst +++ /dev/null @@ -1,75 +0,0 @@ -Using the enhanced request in all your views -============================================== - -This example shows how you can use Django REST framework's enhanced `request` - :class:`request.Request` - in your own views, without having to use the full-blown :class:`views.View` class. - -What can it do for you ? Mostly, it will take care of parsing the request's content, and handling equally all HTTP methods ... - -Before --------- - -In order to support `JSON` or other serial formats, you might have parsed manually the request's content with something like : :: - - class MyView(View): - - def put(self, request, *args, **kwargs): - content_type = request.META['CONTENT_TYPE'] - if (content_type == 'application/json'): - raw_data = request.read() - parsed_data = json.loads(raw_data) - - # PLUS as many `elif` as formats you wish to support ... - - # then do stuff with your data : - self.do_stuff(parsed_data['bla'], parsed_data['hoho']) - - # and finally respond something - -... and you were unhappy because this looks hackish. - -Also, you might have tried uploading files with a PUT request - *and given up* since that's complicated to achieve even with Django 1.3. - - -After ------- - -All the dirty `Content-type` checking and content reading and parsing is done for you, and you only need to do the following : :: - - class MyView(MyBaseViewUsingEnhancedRequest): - - def put(self, request, *args, **kwargs): - self.do_stuff(request.DATA['bla'], request.DATA['hoho']) - # and finally respond something - -So the parsed content is magically available as `.DATA` on the `request` object. - -Also, if you uploaded files, they are available as `.FILES`, like with a normal POST request. - -.. note:: Note that all the above is also valid for a POST request. - - -How to add it to your custom views ? --------------------------------------- - -Now that you're convinced you need to use the enhanced request object, here is how you can add it to all your custom views : :: - - from django.views.generic.base import View - - from djangorestframework.mixins import RequestMixin - from djangorestframework import parsers - - - class MyBaseViewUsingEnhancedRequest(RequestMixin, View): - """ - Base view enabling the usage of enhanced requests with user defined views. - """ - - parser_classes = parsers.DEFAULT_PARSERS - - def dispatch(self, request, *args, **kwargs): - request = self.prepare_request(request) - return super(MyBaseViewUsingEnhancedRequest, self).dispatch(request, *args, **kwargs) - -And then, use this class as a base for all your custom views. - -.. note:: you can see this live in the examples. diff --git a/docs/howto/reverse.rst b/docs/howto/reverse.rst deleted file mode 100644 index 73b8fa4d..00000000 --- a/docs/howto/reverse.rst +++ /dev/null @@ -1,39 +0,0 @@ -Returning URIs from your Web APIs -================================= - -As a rule, it's probably better practice to return absolute URIs from you web APIs, e.g. "http://example.com/foobar", rather than returning relative URIs, e.g. "/foobar". - -The advantages of doing so are: - -* It's more explicit. -* It leaves less work for your API clients. -* There's no ambiguity about the meaning of the string when it's found in representations such as JSON that do not have a native URI type. -* It allows us to easily do things like markup HTML representations with hyperlinks. - -Django REST framework provides two utility functions to make it simpler to return absolute URIs from your Web API. - -There's no requirement for you to use them, but if you do then the self-describing API will be able to automatically hyperlink its output for you, which makes browsing the API much easier. - -reverse(viewname, request, ...) -------------------------------- - -The :py:func:`~reverse.reverse` function has the same behavior as `django.core.urlresolvers.reverse`_, except that it takes a request object and returns a fully qualified URL, using the request to determine the host and port:: - - from djangorestframework.reverse import reverse - from djangorestframework.views import View - - class MyView(View): - def get(self, request): - context = { - 'url': reverse('year-summary', request, args=[1945]) - } - - return Response(context) - -reverse_lazy(viewname, request, ...) ------------------------------------- - -The :py:func:`~reverse.reverse_lazy` function has the same behavior as `django.core.urlresolvers.reverse_lazy`_, except that it takes a request object and returns a fully qualified URL, using the request to determine the host and port. - -.. _django.core.urlresolvers.reverse: https://docs.djangoproject.com/en/dev/topics/http/urls/#reverse -.. _django.core.urlresolvers.reverse_lazy: https://docs.djangoproject.com/en/dev/topics/http/urls/#reverse-lazy diff --git a/docs/howto/setup.rst b/docs/howto/setup.rst deleted file mode 100644 index f0127060..00000000 --- a/docs/howto/setup.rst +++ /dev/null @@ -1,73 +0,0 @@ -.. _setup: - -Setup -===== - -Templates ---------- - -Django REST framework uses a few templates for the HTML and plain text -documenting renderers. You'll need to ensure ``TEMPLATE_LOADERS`` setting -contains ``'django.template.loaders.app_directories.Loader'``. -This will already be the case by default. - -You may customize the templates by creating a new template called -``djangorestframework/api.html`` in your project, which should extend -``djangorestframework/base.html`` and override the appropriate -block tags. For example:: - - {% extends "djangorestframework/base.html" %} - - {% block title %}My API{% endblock %} - - {% block branding %} -

My API

- {% endblock %} - - -Styling -------- - -Django REST framework requires `django.contrib.staticfiles`_ to serve it's css. -If you're using Django 1.2 you'll need to use the seperate -`django-staticfiles`_ package instead. - -You can override the styling by creating a file in your top-level static -directory named ``djangorestframework/css/style.css`` - - -Markdown --------- - -`Python markdown`_ is not required but comes recommended. - -If markdown is installed your :class:`.Resource` descriptions can include -`markdown formatting`_ which will be rendered by the self-documenting API. - -YAML ----- - -YAML support is optional, and requires `PyYAML`_. - - -Login / Logout --------------- - -Django REST framework includes login and logout views that are needed if -you're using the self-documenting API. - -Make sure you include the following in your `urlconf`:: - - from django.conf.urls.defaults import patterns, url - - urlpatterns = patterns('', - ... - url(r'^restframework', include('djangorestframework.urls', namespace='djangorestframework')) - ) - -.. _django.contrib.staticfiles: https://docs.djangoproject.com/en/dev/ref/contrib/staticfiles/ -.. _django-staticfiles: http://pypi.python.org/pypi/django-staticfiles/ -.. _URLObject: http://pypi.python.org/pypi/URLObject/ -.. _Python markdown: http://www.freewisdom.org/projects/python-markdown/ -.. _markdown formatting: http://daringfireball.net/projects/markdown/syntax -.. _PyYAML: http://pypi.python.org/pypi/PyYAML \ No newline at end of file diff --git a/docs/howto/usingcurl.rst b/docs/howto/usingcurl.rst deleted file mode 100644 index eeb8da06..00000000 --- a/docs/howto/usingcurl.rst +++ /dev/null @@ -1,30 +0,0 @@ -Using CURL with django-rest-framework -===================================== - -`curl `_ is a great command line tool for making requests to URLs. - -There are a few things that can be helpful to remember when using CURL with django-rest-framework APIs. - -#. Curl sends an ``Accept: */*`` header by default:: - - curl -X GET http://example.com/my-api/ - -#. Setting the ``Accept:`` header on a curl request can be useful:: - - curl -X GET -H 'Accept: application/json' http://example.com/my-api/ - -#. The text/plain representation is useful for browsing the API:: - - curl -X GET -H 'Accept: text/plain' http://example.com/my-api/ - -#. ``POST`` and ``PUT`` requests can contain form data (ie ``Content-Type: application/x-www-form-urlencoded``):: - - curl -X PUT --data 'foo=bar' http://example.com/my-api/some-resource/ - -#. Or any other content type:: - - curl -X PUT -H 'Content-Type: application/json' --data-binary '{"foo":"bar"}' http://example.com/my-api/some-resource/ - -#. You can use basic authentication to send the username and password:: - - curl -X GET -H 'Accept: application/json' -u : http://example.com/my-api/ diff --git a/docs/howto/usingurllib2.rst b/docs/howto/usingurllib2.rst deleted file mode 100644 index 6320dc20..00000000 --- a/docs/howto/usingurllib2.rst +++ /dev/null @@ -1,39 +0,0 @@ -Using urllib2 with Django REST Framework -======================================== - -Python's standard library comes with some nice modules -you can use to test your api or even write a full client. - -Using the 'GET' method ----------------------- - -Here's an example which does a 'GET' on the `model-resource` example -in the sandbox.:: - - >>> import urllib2 - >>> r = urllib2.urlopen('htpp://rest.ep.io/model-resource-example') - >>> r.getcode() # Check if the response was ok - 200 - >>> print r.read() # Examin the response itself - [{"url": "http://rest.ep.io/model-resource-example/1/", "baz": "sdf", "foo": true, "bar": 123}] - -Using the 'POST' method ------------------------ - -And here's an example which does a 'POST' to create a new instance. First let's encode -the data we want to POST. We'll use `urllib` for encoding and the `time` module -to send the current time as as a string value for our POST.:: - - >>> import urllib, time - >>> d = urllib.urlencode((('bar', 123), ('baz', time.asctime()))) - -Now use the `Request` class and specify the 'Content-type':: - - >>> req = urllib2.Request('http://rest.ep.io/model-resource-example/', data=d, headers={'Content-Type':'application/x-www-form-urlencoded'}) - >>> resp = urllib2.urlopen(req) - >>> resp.getcode() - 201 - >>> resp.read() - '{"url": "http://rest.ep.io/model-resource-example/4/", "baz": "Fri Dec 30 18:22:52 2011", "foo": false, "bar": 123}' - -That should get you started to write a client for your own api. -- cgit v1.2.3