Marshmallow jsonapi is a ext of marshmallow to provide a default contract for GERU REST's API's
- Go to directory and, install the lib
pip install geru.marshmallow-jsonapi
- Just code with it. Inside you python app:
from geru.marshmallow_jsonapi import JsonApificator
- Define your marshmallow schema and decorate it
from marshmallow import Schema, fields
from geru.marshmallow_jsonapi import JsonApificator
@JsonApificator()
class BookSchema(Schema):
id = fields.Str(dump_only=True)
title = fields.Str()
# This Schema expects a payload like:
{
"data":{
"attributtes": {
"title": "This is my personal title"
},
"id": 1,
"type": "books"
}
}- You can customize the default JsonApificator attributes:
from marshmallow import Schema, fields, validate
from geru.marshmallow_jsonapi import JsonApificator
@JsonApificator(id={"required": True}, type_={"validate": [validate.Length(min=8, max=200)]}, attributes={"required": True})
class BookSchema(Schema):
id = fields.Str(dump_only=True)
title = fields.Str()
# This Schema expects a payload like:
{
"data": {
"attributtes": { # This is required
"title": "This is my personal title"
},
"id": 1, # This is required
"type": "books" # This is required and the min length > 8 and max length < 200
}
}- Working with relationships:
from marshmallow import Schema, fields, ValidationError
from geru.marshmallow_jsonapi import JsonApificator
class PublishSchema(Schema):
name = fields.Str()
class AuthorSchema(Schema):
name = fields.Str()
def must_be_book(data):
if data != 'book':
raise ValidationError('type must be book')
@JsonApificator(type_={"validate": must_be_book, "required": True}, relationships=[{"relationships": AuthorSchema,
"extra_kwargs": {"required": True}},
{"relationships": PublishSchema}])
class BookSchemaRelationship(Schema):
title = fields.Str()
# This Schema expects a payload like:
{
"data": {
"attributtes": { # This is required
"title": "This is my personal title"
},
"id": 1, # This is required
"type": "book", # The type must be book
"relationships": {
"author_schema": {
"name": "Jose"
},
"publish_schema": {
"name": "Martin"
}
}
}
}- Default JsonApi Error Exception: Example:
from geru.marshmallow_jsonapi.exceptions import BaseApiException
message = 'Invalid credentials'
e = BaseApiException(message=message, status=403)
e.message == {'error': message, 'status': 403}from cornice import Service
from cornice.validators import marshmallow_body_validator
from marshmallow import Schema, fields
from geru.marshmallow_jsonapi import JsonApificator
manage_books = Service(name='manage_books',
path='/books/{bookId}',
description='Manage books')
@JsonApificator(type_={"required": True}, params_description={"bookId": "Book UUID"})
class BookSchema(Schema):
title = fields.Str()
book_response_schemas = {
'200': BookSchema,
}
@manage_books.put(schema=BookSchema,
validators=(marshmallow_body_validator,),
response_schemas=book_response_schemas,
content_type='application/json')
def _put_books(request):
# TODO: do something
return {}- Assumptions:
- Python ^2.7 or ^3.6 installed.
- Clone the lib (and go to directory)
git clone https://github.com/geru-br/marshmallow-jsonapi
cd marshmallow-jsonapi
- Create and activate a virtual environment
python3 -m venv venv
source venv/bin/activate
- Upgrade setuptools and install poetry
pip install --upgrade pip setuptools
pip install poetry==MANDATORY REPLACING
- Install project
make install
- Run tests
make test-all
- Bump version
To bump a minor version, just run:
make bump-version
If you need to generate a major, patch or another different version you can read here for details.
- TODO: Insert here relevant information about project's structure, concepts and operation. Get a nice example from https://github.com/geru-br/arkham/blob/master/README.md.
This package was created with https://github.com/geru-br/cookiecutter-geru-pypackage project template.