From defda260e47c9871205488bc53d40b707aa9367c Mon Sep 17 00:00:00 2001 From: Anwinkp <48901971+Anwinkp@users.noreply.github.com> Date: Mon, 25 Mar 2019 12:19:43 +0530 Subject: [PATCH] Update README.md --- README.md | 175 +++++++++++++++++++++--------------------------------- 1 file changed, 69 insertions(+), 106 deletions(-) diff --git a/README.md b/README.md index 66079edf0..0d9e9e161 100644 --- a/README.md +++ b/README.md @@ -46,51 +46,66 @@ Some reasons you might want to use REST framework: There is a live example API for testing purposes, [available here][sandbox]. **Below**: *Screenshot from the browsable API* +Funding -![Screenshot][image] +REST framework is a collaboratively funded project. If you use REST framework commercially we strongly encourage you to invest in its continued development by signing up for a paid plan. ----- +The initial aim is to provide a single full-time position on REST framework. Every single sign-up makes a significant impact on making that possible. -# Requirements +Many thanks to all our wonderful sponsors, and in particular to our premium backers, Sentry, Stream, Rollbar, Cadre, Kloudless, Release History, and Lights On Software. +Overview -* Python (2.7, 3.4, 3.5, 3.6, 3.7) -* Django (1.11, 2.0, 2.1, 2.2) +Django REST framework is a powerful and flexible toolkit for building Web APIs. -We **highly recommend** and only officially support the latest patch release of -each Python and Django series. +Some reasons you might want to use REST framework: -# Installation + The Web-browsable API is a huge usability win for your developers. + Authentication policies including optional packages for OAuth1a and OAuth2. + Serialization that supports both ORM and non-ORM data sources. + Customizable all the way down - just use regular function-based views if you don't need the more powerful features. + Extensive documentation, and great community support. -Install using `pip`... +There is a live example API for testing purposes, available here. - pip install djangorestframework +Below: Screenshot from the browsable API -Add `'rest_framework'` to your `INSTALLED_APPS` setting. +Screenshot +Requirements - INSTALLED_APPS = ( - ... - 'rest_framework', - ) + Python (2.7, 3.4, 3.5, 3.6, 3.7) + Django (1.11, 2.0, 2.1, 2.2) -# Example +We highly recommend and only officially support the latest patch release of each Python and Django series. +Installation + +Install using pip... + +pip install djangorestframework + +Add 'rest_framework' to your INSTALLED_APPS setting. + +INSTALLED_APPS = ( + ... + 'rest_framework', +) + +Example Let's take a look at a quick example of using REST framework to build a simple model-backed API for accessing users and groups. Startup up a new project like so... - pip install django - pip install djangorestframework - django-admin startproject example . - ./manage.py migrate - ./manage.py createsuperuser +pip install django +pip install djangorestframework +django-admin startproject example . +./manage.py migrate +./manage.py createsuperuser +Now edit the example/URLs.py module in your project: -Now edit the `example/urls.py` module in your project: - -```python -from django.conf.urls import url, include +from django.conf.URLs import URL, include from django.contrib.auth.models import User -from rest_framework import serializers, viewsets, routers +from rest_framework import serializers, view sets, routers # Serializers define the API representation. class UserSerializer(serializers.HyperlinkedModelSerializer): @@ -112,17 +127,15 @@ router.register(r'users', UserViewSet) # Wire up our API using automatic URL routing. # Additionally, we include login URLs for the browsable API. -urlpatterns = [ +URL patterns = [ url(r'^', include(router.urls)), url(r'^api-auth/', include('rest_framework.urls', namespace='rest_framework')) ] -``` We'd also like to configure a couple of settings for our API. -Add the following to your `settings.py` module: +Add the following to your settings.py module: -```python INSTALLED_APPS = ( ... # Make sure to include the default installed apps here. 'rest_framework', @@ -135,94 +148,44 @@ REST_FRAMEWORK = { 'rest_framework.permissions.DjangoModelPermissionsOrAnonReadOnly' ] } -``` That's it, we're done! - ./manage.py runserver +./manage.py runserver -You can now open the API in your browser at `http://127.0.0.1:8000/`, and view your new 'users' API. If you use the `Login` control in the top right corner you'll also be able to add, create and delete users from the system. +You can now open the API in your browser at http://127.0.0.1:8000/, and view your new 'users' API. If you use the Login control in the top right corner you'll also be able to add, create and delete users from the system. -You can also interact with the API using command line tools such as [`curl`](https://curl.haxx.se/). For example, to list the users endpoint: +You can also interact with the API using command line tools such as curl. For example, to list the user's endpoint: - $ curl -H 'Accept: application/json; indent=4' -u admin:password http://127.0.0.1:8000/users/ - [ - { - "url": "http://127.0.0.1:8000/users/1/", - "username": "admin", - "email": "admin@example.com", - "is_staff": true, - } - ] +$ curl -H 'Accept: application/json; indent=4' -u admin:password http://127.0.0.1:8000/users/ +[ + { + "url": "http://127.0.0.1:8000/users/1/", + "username": "admin", + "email": "admin@example.com", + "is_staff": true, + } +] Or to create a new user: - $ curl -X POST -d username=new -d email=new@example.com -d is_staff=false -H 'Accept: application/json; indent=4' -u admin:password http://127.0.0.1:8000/users/ - { - "url": "http://127.0.0.1:8000/users/2/", - "username": "new", - "email": "new@example.com", - "is_staff": false, - } +$ curl -X POST -d username=new -d email=new@example.com -d is_staff=false -H 'Accept: application/json; indent=4' -u admin:password http://127.0.0.1:8000/users/ +{ + "url": "http://127.0.0.1:8000/users/2/", + "username": "new", + "email": "new@example.com", + "is_staff": false, +} -# Documentation & Support +Documentation & Support -Full documentation for the project is available at [https://www.django-rest-framework.org/][docs]. +Full documentation for the project is available at https://www.django-rest-framework.org/. -For questions and support, use the [REST framework discussion group][group], or `#restframework` on freenode IRC. +For questions and support, use the REST framework discussion group, or #restframework on Freenode IRC. -You may also want to [follow the author on Twitter][twitter]. +You may also want to follow the author on Twitter. +Security -# Security +If you believe you've found something in Django REST framework which has security implications, please do not raise the issue in a public forum. -If you believe you've found something in Django REST framework which has security implications, please **do not raise the issue in a public forum**. - -Send a description of the issue via email to [rest-framework-security@googlegroups.com][security-mail]. The project maintainers will then work with you to resolve any issues where required, prior to any public disclosure. - -[build-status-image]: https://secure.travis-ci.org/encode/django-rest-framework.svg?branch=master -[travis]: https://travis-ci.org/encode/django-rest-framework?branch=master -[coverage-status-image]: https://img.shields.io/codecov/c/github/encode/django-rest-framework/master.svg -[codecov]: https://codecov.io/github/encode/django-rest-framework?branch=master -[pypi-version]: https://img.shields.io/pypi/v/djangorestframework.svg -[pypi]: https://pypi.org/project/djangorestframework/ -[twitter]: https://twitter.com/_tomchristie -[group]: https://groups.google.com/forum/?fromgroups#!forum/django-rest-framework -[sandbox]: https://restframework.herokuapp.com/ - -[funding]: https://fund.django-rest-framework.org/topics/funding/ -[sponsors]: https://fund.django-rest-framework.org/topics/funding/#our-sponsors - -[rover-img]: https://raw.githubusercontent.com/encode/django-rest-framework/master/docs/img/premium/rover-readme.png -[sentry-img]: https://raw.githubusercontent.com/encode/django-rest-framework/master/docs/img/premium/sentry-readme.png -[stream-img]: https://raw.githubusercontent.com/encode/django-rest-framework/master/docs/img/premium/stream-readme.png -[rollbar-img]: https://raw.githubusercontent.com/encode/django-rest-framework/master/docs/img/premium/rollbar-readme.png -[cadre-img]: https://raw.githubusercontent.com/encode/django-rest-framework/master/docs/img/premium/cadre-readme.png -[load-impact-img]: https://raw.githubusercontent.com/encode/django-rest-framework/master/docs/img/premium/load-impact-readme.png -[kloudless-img]: https://raw.githubusercontent.com/encode/django-rest-framework/master/docs/img/premium/kloudless-readme.png -[release-history-img]: https://raw.githubusercontent.com/encode/django-rest-framework/master/docs/img/premium/release-history.png -[lightson-img]: https://raw.githubusercontent.com/encode/django-rest-framework/master/docs/img/premium/lightson-readme.png - -[rover-url]: http://jobs.rover.com/ -[sentry-url]: https://getsentry.com/welcome/ -[stream-url]: https://getstream.io/try-the-api/?utm_source=drf&utm_medium=banner&utm_campaign=drf -[rollbar-url]: https://rollbar.com/ -[cadre-url]: https://cadre.com/ -[load-impact-url]: https://loadimpact.com/?utm_campaign=Sponsorship%20links&utm_source=drf&utm_medium=drf -[kloudless-url]: https://hubs.ly/H0f30Lf0 -[release-history-url]: https://releasehistory.io -[lightson-url]: https://lightsonsoftware.com - -[oauth1-section]: https://www.django-rest-framework.org/api-guide/authentication/#django-rest-framework-oauth -[oauth2-section]: https://www.django-rest-framework.org/api-guide/authentication/#django-oauth-toolkit -[serializer-section]: https://www.django-rest-framework.org/api-guide/serializers/#serializers -[modelserializer-section]: https://www.django-rest-framework.org/api-guide/serializers/#modelserializer -[functionview-section]: https://www.django-rest-framework.org/api-guide/views/#function-based-views -[generic-views]: https://www.django-rest-framework.org/api-guide/generic-views/ -[viewsets]: https://www.django-rest-framework.org/api-guide/viewsets/ -[routers]: https://www.django-rest-framework.org/api-guide/routers/ -[serializers]: https://www.django-rest-framework.org/api-guide/serializers/ -[authentication]: https://www.django-rest-framework.org/api-guide/authentication/ -[image]: https://www.django-rest-framework.org/img/quickstart.png - -[docs]: https://www.django-rest-framework.org/ -[security-mail]: mailto:rest-framework-security@googlegroups.com +Send a description of the issue via email to rest-framework-security@googlegroups.com. The project maintainers will then work with you to resolve any issues where required, prior to any public disclosure.