Relationship resources (#3)

* Added BaseRelationshipResource and tests

* More documentation through comments and docstrings

* Modify JSONAPIRelationship to pass allow_none=True

* Added example for BaseRelationshipResource in sample-plain

* Added basic example for setting up a relationship resource in readme

Author: vladmunteanu

README.md

@@ -20,13 +20,13 @@ Since this project is under development, please pin your dependencies to avoid p
 - basic json:api serialization
 - including related resources
 - starlette friendly route generation
-- exception handlers to serialize as json:api responses 
+- exception handlers to serialize as json:api responses
+- relationship resources 
 
 ### Todo:
 - sparse fields
 - pagination helpers
 - sorting helpers
-- relationship resources
 - documentation
 - examples for other ORMs
 
@@ -162,6 +162,67 @@ class ExampleResource(BaseResource):
         return await self.serialize(example)
 ```
 
+### Defining a relationship resource
+You can choose to define a relationship resource by subclassing `starlette_jsonapi.resource.BaseRelationshipResource`.
+
+A json:api compliant service might implement GET, POST, PATCH, DELETE HTTP methods on a relationship resource,
+so the `BaseRelationshipResource` comes with 4 methods that you can override:
+- `get -> handling GET /<parent_type>/<parent_id>/relationships/<relationship_name>`
+- `patch -> handling PATCH /<parent_type>/<parent_id>/relationships/<relationship_name>`
+- `delete -> handling DELETE /<parent_type>/<parent_id>/relationships/<relationship_name>`
+- `post -> handling POST /<parent_type>/<parent_id>/relationships/<relationship_name>`
+
+All methods return 405 Method Not Allowed by default.
+You can also customize `allowed_methods` to a subset of the above HTTP methods.
+
+When defining a relationship resource, the following class attributes must be set:
+- `parent_resource` -> must point to the BaseResource subclass that is exposing the parent resource
+- `relationship_name` -> must contain the relationship name, as found on `parent_resource.schema`
+
+Example:
+```python
+from marshmallow_jsonapi import fields
+from starlette.applications import Starlette
+from starlette_jsonapi.fields import JSONAPIRelationship
+from starlette_jsonapi.resource import BaseRelationshipResource, BaseResource
+from starlette_jsonapi.schema import JSONAPISchema
+
+class EmployeeSchema(JSONAPISchema):
+    class Meta:
+        type_ = 'employees'
+        self_route = 'employees:get'
+        self_route_kwargs = {'id': '<id>'}
+        self_route_many = 'employees:get_all'
+
+    id = fields.Str(dump_only=True)
+    name = fields.Str()
+
+    manager = JSONAPIRelationship(
+        type_='employees',
+        schema='EmployeeSchema',
+        include_resource_linkage=True,
+        self_route='employees:manager',
+        self_route_kwargs={'parent_id': '<id>'},
+        related_route='employees:get',
+        related_route_kwargs={'id': '<id>'},
+    )
+
+
+class EmployeeResource(BaseResource):
+    type_ = 'employees'
+    schema = EmployeeSchema    
+
+
+class EmployeeManagerResource(BaseRelationshipResource):
+    parent_resource = EmployeeResource
+    relationship_name = 'manager'
+
+
+app = Starlette()
+EmployeeResource.register_routes(app=app, base_path='/')
+EmployeeManagerResource.register_routes(app=app, base_path='/')
+```
+
 #### Registering resource paths
 To register a defined resource class, we need to add the appropriate paths to the Starlette app.
 Considering the ExampleResource implementation above, it's as simple as:

examples/README.md

@@ -24,7 +24,7 @@ You can then access [users](http://127.0.0.1:8000/api/users/) and [organizations
 
 ## 1. sample-plain
 
-Contains a basic implementation of 2 resources, `users` and `organizations` using plain Python classes.
+Contains a basic implementation of 3 resources: `users`, `teams` and `organizations` using plain Python classes.
 
 #### Running:
 In order to start the service on http://127.0.0.1:8000/, you can run:

examples/sample-plain/accounts/app.py

@@ -10,8 +10,10 @@ def create_app():
     register_jsonapi_exception_handlers(app)
 
     # register routes
-    from accounts.resources import users, organizations
+    from accounts.resources import users, organizations, teams
     users.UsersResource.register_routes(app, '/api')
     organizations.OrganizationsResource.register_routes(app, '/api')
+    teams.TeamsResource.register_routes(app, '/api')
+    teams.TeamUsersResource.register_routes(app)
 
     return app

examples/sample-plain/accounts/exceptions.py

@@ -7,3 +7,7 @@ class OrganizationNotFound(ResourceNotFound):
 
 class UserNotFound(ResourceNotFound):
     detail = 'User not found.'
+
+
+class TeamNotFound(ResourceNotFound):
+    detail = 'Team not found.'

examples/sample-plain/accounts/models.py

@@ -34,15 +34,22 @@ def delete(self) -> None:
 
 
 class Organization(Model):
-    __db_name__: str = 'organizations'
+    __db_name__ = 'organizations'
 
     name: str
     contact_url: Optional[str] = None
     contact_phone: Optional[str] = None
 
 
 class User(Model):
-    __db_name__: str = 'users'
+    __db_name__ = 'users'
 
     username: str
     organization: Organization
+
+
+class Team(Model):
+    __db_name__ = 'teams'
+
+    name: str
+    users: List[User]

examples/sample-plain/accounts/resources/teams.py

@@ -0,0 +1,185 @@
+import logging
+from typing import List
+
+from marshmallow_jsonapi import fields
+from starlette.responses import Response
+
+from starlette_jsonapi.fields import JSONAPIRelationship
+from starlette_jsonapi.resource import BaseResource, BaseRelationshipResource
+from starlette_jsonapi.responses import JSONAPIResponse
+from starlette_jsonapi.schema import JSONAPISchema
+
+from accounts.exceptions import TeamNotFound, UserNotFound
+from accounts.models import User, Team
+
+logger = logging.getLogger(__name__)
+
+
+class TeamSchema(JSONAPISchema):
+    id = fields.Str(dump_only=True)
+    name = fields.Str(required=True)
+
+    users = JSONAPIRelationship(
+        type_='users',
+        schema='UserSchema',
+        include_resource_linkage=True,
+        many=True,
+        required=True,
+    )
+
+    class Meta:
+        type_ = 'teams'
+        self_route = 'teams:get'
+        self_route_kwargs = {'id': '<id>'}
+        self_route_many = 'teams:get_all'
+
+
+class TeamsResource(BaseResource):
+    type_ = 'teams'
+    schema = TeamSchema
+    id_mask = 'int'
+
+    async def prepare_relations(self, obj: Team, relations: List[str]):
+        """
+        We override this to allow `included` requests against this resource,
+        but we don't actually have to do anything here.
+        The attribute is already populated because we're using plain NamedTuples.
+        """
+        return None
+
+    async def get(self, id=None, *args, **kwargs) -> Response:
+        if not id:
+            raise TeamNotFound
+        team = Team.get_item(id)
+        if not team:
+            raise TeamNotFound
+
+        return await self.serialize(data=team)
+
+    async def patch(self, id=None, *args, **kwargs) -> Response:
+        if not id:
+            raise TeamNotFound
+        team = Team.get_item(id)
+        if not team:
+            raise TeamNotFound
+
+        json_body = await self.deserialize_body(partial=True)
+        name = json_body.get('name')
+        if name:
+            team.name = name
+
+        user_ids = json_body.get('users')
+        if user_ids:
+            users = []
+            for user_id in user_ids:
+                user = User.get_item(int(user_id))
+                if not user:
+                    raise UserNotFound
+                users.append(user)
+            team.users = users
+
+        team.save()
+
+        return await self.serialize(data=team)
+
+    async def delete(self, id=None, *args, **kwargs) -> Response:
+        if not id:
+            raise TeamNotFound
+        team = Team.get_item(id)
+        if not team:
+            raise TeamNotFound
+
+        team.delete()
+
+        return JSONAPIResponse(status_code=204)
+
+    async def get_all(self, *args, **kwargs) -> Response:
+        teams = Team.get_items()
+        return await self.serialize(data=teams, many=True)
+
+    async def post(self, *args, **kwargs) -> Response:
+        json_body = await self.deserialize_body()
+
+        team = Team()
+        name = json_body.get('name')
+        if name:
+            team.name = name
+
+        user_ids = json_body['users']
+        users = []
+        for user_id in user_ids:
+            user = User.get_item(int(user_id))
+            if not user:
+                raise UserNotFound
+            users.append(user)
+        team.users = users
+
+        team.save()
+
+        result = await self.serialize(data=team)
+        result.status_code = 201
+        return result
+
+
+class TeamUsersResource(BaseRelationshipResource):
+    parent_resource = TeamsResource
+    relationship_name = 'users'
+
+    async def get(self, parent_id: str, *args, **kwargs) -> Response:
+        team = Team.get_item(int(parent_id))
+        if not team:
+            raise TeamNotFound
+        return await self.serialize(data=team)
+
+    async def patch(self, parent_id: str, *args, **kwargs) -> Response:
+        team = Team.get_item(int(parent_id))
+        if not team:
+            raise TeamNotFound
+
+        user_ids = await self.deserialize_ids()
+        if not user_ids:
+            users = []
+        else:
+            users = []
+            for user_id in user_ids:
+                user = User.get_item(int(user_id))
+                if not user:
+                    raise UserNotFound
+                users.append(user)
+        team.users = users
+        team.save()
+        return await self.serialize(data=team)
+
+    async def post(self, parent_id: str, *args, **kwargs) -> Response:
+        team = Team.get_item(int(parent_id))
+        if not team:
+            raise TeamNotFound
+
+        user_ids = await self.deserialize_ids()
+        if not user_ids:
+            users = []
+        else:
+            users = team.users
+            for user_id in user_ids:
+                user = User.get_item(int(user_id))
+                if not user:
+                    raise UserNotFound
+                users.append(user)
+        team.users = users
+        team.save()
+        return await self.serialize(data=team)
+
+    async def delete(self, parent_id: str, *args, **kwargs) -> Response:
+        team = Team.get_item(int(parent_id))
+        if not team:
+            raise TeamNotFound
+        user_ids = await self.deserialize_ids()
+        if not user_ids:
+            user_ids = []
+        users = []
+        for user in team.users:
+            if str(user.id) not in user_ids:
+                users.append(user)
+        team.users = users
+        team.save()
+        return await self.serialize(data=team)