{"id":13814358,"url":"https://github.com/jarcoal/django-sliver","last_synced_at":"2025-04-14T08:51:45.777Z","repository":{"id":4989233,"uuid":"6147287","full_name":"jarcoal/django-sliver","owner":"jarcoal","description":"Lightweight REST API built on top of Django's class-based generic views","archived":false,"fork":false,"pushed_at":"2019-11-26T08:59:46.000Z","size":33,"stargazers_count":106,"open_issues_count":5,"forks_count":6,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-03-27T22:22:45.235Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"ackmanndickenson/has_many_polymorphs","license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jarcoal.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2012-10-09T20:29:27.000Z","updated_at":"2023-09-08T16:35:42.000Z","dependencies_parsed_at":"2022-07-09T00:30:20.899Z","dependency_job_id":null,"html_url":"https://github.com/jarcoal/django-sliver","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jarcoal%2Fdjango-sliver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jarcoal%2Fdjango-sliver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jarcoal%2Fdjango-sliver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jarcoal%2Fdjango-sliver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jarcoal","download_url":"https://codeload.github.com/jarcoal/django-sliver/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248571839,"owners_count":21126522,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-04T04:01:54.963Z","updated_at":"2025-04-14T08:51:45.756Z","avatar_url":"https://github.com/jarcoal.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.org/jarcoal/django-sliver.svg?branch=master)](https://travis-ci.org/jarcoal/django-sliver)\n\n# django-sliver\n### Lightweight REST API for Django built on top of generic views\n\n----\n\n### Why django-sliver?\n\nSliver was designed for sites that just need a simple API for their front-end ([backbone](https://github.com/documentcloud/backbone), etc), without all the bells and whistles (and headaches :) of a solution like [django-tastypie](https://github.com/toastdriven/django-tastypie).\n\nSome things to note:\n\n* It's built on top of Django's generic views, so a lot of the methods you are used to overriding are here.\n* It only works with Django's ORM, and there are no plans to expand on that.\n* It provides no authentication/authorization systems, instead relying on whatever auth backend you have to do the heavy lifting.\n* Like the generic views, it relies heavily on mixins to provide additional functionality.\n\n----\n\n### Requirements\n\nThere are no dependencies beyond having Django \u003e= 1.11\n\n----\n\n### Installation\n\n`pip install -e git+git@github.com:jarcoal/django-sliver.git#egg=django-sliver`\n\n----\n\n### What's it look like?\n\nviews.py\n```python\n# sliver objects\nfrom sliver.views import ModelResource, CollectionResource\nfrom sliver.mixins import JSONMixin\n\n# your data\nfrom products.models import Product\n\n\nclass ProductCollectionResource(JSONMixin, CollectionResource):\n\tmodel = Product\n\nclass ProductResource(JSONMixin, ModelResource):\n\tmodel = Product\n```\n\n`urls.py`:\n```python\nfrom django.conf.urls import patterns, url\nfrom views import ProductCollectionResource, ProductResource\n\nurlpatterns = patterns('',\n\turl(r'^products/$', ProductCollectionResource.as_view(), name='api-products-collection'),\n\turl(r'^products/(?P\u003cpk\u003e\\d+)/$', ProductResource.as_view(), name='api-products-model'),\n)\n```\n\nThat's all you need for a basic JSON API.\n\n----\n\n### `Views`\n\nThere are two main views that will be important to you.  Remember, they both inherit from Django's [View](https://github.com/django/django/blob/master/django/views/generic/base.py) class, so you can override `dispatch()`, `get()`, `post()`, etc, whenever you want.\n\n#### `sliver.views.ModelResource`\n\nModelResource is designed to handle requests relating to a single model object.  It's mixed with Django's [SingleObjectMixin](https://github.com/django/django/blob/master/django/views/generic/detail.py), so methods like `get_object()` and `get_queryset()` can easily be overrided.\n\n#### `sliver.views.CollectionResource`\n\nCollectionResource is designed to handle requests relating to a collection of model objects.  Similar to ModelResource, it mixes with Django's [MultipleObjectMixin](https://github.com/django/django/blob/master/django/views/generic/list.py), so those methods are available.\n\n----\n\n### Limiting incoming/outgoing fields\n\nHandling which fields are shown / updateable is just like using Django's form views.  Continuing our example:\n\n```python\nclass ProductCollectionResource(JSONMixin, CollectionResource):\n\t#this will limit the output to these three fields.  it will restrict updates to just them as well.\n\tfields = ['id', 'name', 'description']\n\n\t#like form views, exclude also works\n\texclude = ['secret_key']\n```\n\n----\n\n### Serializing / Deserializing\n\nSerializing is really up to you; the bare resources don't implement anything in particular. There is a JSONMixin provided that you can add to your resource that will aide in parsing/rendering your resource in JSON.\n\nWhen a request comes in, the `parse()` method on your resource will be called with `request.body` passed to it.  Here is an example for JSON:\n\n```python\ndef parse(self, raw_data):\n\treturn json.loads(raw_data)\n```\n\nNOTE: If `request.body` isn't all you need to parse a request, remember this is just a generic view, the request object is available at `self.request`.\n\nWhen a response is ready to go out, the `render()` method is called on your resource.  Again, a JSON example:\n\n```python\ndef render(self, data):\n\treturn json.dumps(data)\n```\n\n----\n\n### Filtering\n\nFiltering can easily be applied by overriding `get_queryset()` and applying your own logic.  However, if you need a simple solution, you can add the `FiltersMixin` to your resource (usually on collection).  Continuing our basic example from above:\n\n```python\nfrom sliver.mixins import FiltersMixin\n\nclass ProductCollectionResource(FiltersMixin, JSONMixin, CollectionResource):\n\tfilters = ['name__contains', 'date_added__gt']\n```\n\nAll filters must be specified in the `filters` attribute, otherwise they are ignored.\n\nIf you need more advanced filtering, you can override `get_filters()` which should return a dictionary of filters that will be applied to the queryset.  You can go one step further than that by overriding the `get_queryset()` method and doing exactly what you want with the queryset.\n\n----\n\n### Relationships\n\nRelationships are always a trick in APIs, so I've tried to make them as simple as possible.  Both to-one and to-many relationships are possible.  Example:\n\n```python\nclass ProductResource(JSONMixin, CollectionResource):\n\tmodel = Product\n\n\trelationships = {\n\t\t'vendor': {},\t\t\t#to-one\n\t\t'feature_set': {}\t\t#to-many\n\t}\n```\n\nIf you need to exclude some fields from your related models, that can easily be done:\n\n```python\nrelationships = {\n\t'vendor': {\n\t\t'exclude': ['private_notes']\n\t},\n\t'feature_set': {\n\t\t'fields': ['id', 'name']\n\t}\n}\n```\n\nDeeper relationships are denoted by double underscores:\n\n```python\nrelationships = {\n\t'vendor': {},\n\t'vendor__parent_company': {}\n}\n```\n\n----\n\n### URIs\n\nBy default, the resources will not insert any URIs into the responses.  For many, this is fine, but not all.  Sliver ships with a `URIMixin` that provides this functionality.  Example:\n\n```python\nclass ProductCollectionResource(URIMixin, JSONMixin, CollectionResource):\n\t#this should be the 'name' parameter you used in your URL patterns\n\tmodel_resource_name = 'api-product-model'\n\n\t#this is the name of the attribute you want serialized into your responses\n\turi_attribute_name = '_uri'\n```\n\nThis is nice, but it won't insert URIs into related objects.  This will:\n\n```python\nrelationships = {\n\t'vendor': {\n\t\t'model_resource_name': 'api-vendor-model'\n\t}\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjarcoal%2Fdjango-sliver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjarcoal%2Fdjango-sliver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjarcoal%2Fdjango-sliver/lists"}