encode/django-rest-framework
1
1
Fork 0
mirror of https://github.com/encode/django-rest-framework.git synced 2025-07-30 01:49:50 +03:00
Code Issues Packages Projects Releases Wiki Activity

Update README.md

Browse Source
This commit is contained in:
Anwinkp 2019-03-25 12:19:43 +05:30 committed by GitHub
parent b25d245b89
commit defda260e4
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 69 additions and 106 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

175
README.md
View File

@ -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.