encode/django-rest-frameworkPublic

NotificationsYou must be signed in to change notification settings
Fork7k
Star29.3k

Web APIs for Django. 🎸

License

View license

29.3k stars 7k forks Branches Tags Activity

Star

Notifications

You must be signed in to change notification settings

Branches Tags

Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 8,872 Commits
.github		.github
.tx		.tx
docs		docs
docs_theme		docs_theme
licenses		licenses
requirements		requirements
rest_framework		rest_framework
tests		tests
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE.md		LICENSE.md
MANIFEST.in		MANIFEST.in
PULL_REQUEST_TEMPLATE.md		PULL_REQUEST_TEMPLATE.md
README.md		README.md
SECURITY.md		SECURITY.md
codecov.yml		codecov.yml
mkdocs.yml		mkdocs.yml
requirements.txt		requirements.txt
runtests.py		runtests.py
setup.cfg		setup.cfg
setup.py		setup.py
tox.ini		tox.ini

Repository files navigation

Django REST framework

Awesome web-browsable Web APIs.

Full documentation for the project is available athttps://www.django-rest-framework.org/.

Funding

REST framework is acollaboratively funded project. If you useREST framework commercially we strongly encourage you to invest in itscontinued development bysigning 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 towards making that possible.

Many thanks to all ourwonderful sponsors, and in particular to our premium backers,Sentry,Stream,Spacinov,Retool,bit.io,PostHog,CryptAPI,FEZTO,Svix, andZuplo.

Overview

Django REST framework is a powerful and flexible toolkit for building Web APIs.

Some reasons you might want to use REST framework:

The Web browsable API is a huge usability win for your developers.
Authentication policies including optional packages forOAuth1a andOAuth2.
Serialization that supports bothORM andnon-ORM data sources.
Customizable all the way down - just useregular function-based views if you don't need themore powerful features.
Extensive documentation, andgreat community support.

Below:Screenshot from the browsable API

Requirements

Python 3.9+
Django 4.2, 5.0, 5.1, 5.2

Wehighly recommend and only officially support the latest patch release ofeach Python and Django series.

Installation

Install usingpip...

pip install djangorestframework

Add'rest_framework' to yourINSTALLED_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 djangopip install djangorestframeworkdjango-admin startproject example ../manage.py migrate./manage.py createsuperuser

Now edit theexample/urls.py module in your project:

fromdjango.contrib.auth.modelsimportUserfromdjango.urlsimportinclude,pathfromrest_frameworkimportrouters,serializers,viewsets# Serializers define the API representation.classUserSerializer(serializers.HyperlinkedModelSerializer):classMeta:model=Userfields= ['url','username','email','is_staff']# ViewSets define the view behavior.classUserViewSet(viewsets.ModelViewSet):queryset=User.objects.all()serializer_class=UserSerializer# Routers provide a way of automatically determining the URL conf.router=routers.DefaultRouter()router.register(r'users',UserViewSet)# Wire up our API using automatic URL routing.# Additionally, we include login URLs for the browsable API.urlpatterns= [path('',include(router.urls)),path('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 yoursettings.py module:

INSTALLED_APPS= [    ...# Make sure to include the default installed apps here.'rest_framework',]REST_FRAMEWORK= {# Use Django's standard `django.contrib.auth` permissions,# or allow read-only access for unauthenticated users.'DEFAULT_PERMISSION_CLASSES': ['rest_framework.permissions.DjangoModelPermissionsOrAnonReadOnly',    ]}

That's it, we're done!

./manage.py runserver

You can now open the API in your browser athttp://127.0.0.1:8000/, and view your new 'users' API. If you use theLogin 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 ascurl. For example, to list the users 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,    }]

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,}