Skip to main content

JSON API 1.0 (https://jsonapi.org) formatting with marshmallow

Project description

Latest version Travis-CI

Homepage: http://marshmallow-jsonapi.rtfd.org/

JSON API 1.0 (https://jsonapi.org) formatting with marshmallow.

marshmallow-jsonapi provides a simple way to produce JSON API-compliant data in any Python web framework.

from marshmallow_jsonapi import Schema, fields

class PostSchema(Schema):
    id = fields.Str(dump_only=True)
    title = fields.Str()

    author = fields.HyperlinkRelated(
        '/authors/{author_id}',
        url_kwargs={'author_id': '<author.id>'},
    )

    comments = fields.HyperlinkRelated(
        '/posts/{post_id}/comments',
        url_kwargs={'post_id': '<id>'},
        # Include resource linkage
        many=True, include_data=True,
        type_='comments'
    )

    class Meta:
        type_ = 'posts'


post_schema = PostSchema()
post_schema.dump(post).data
# {
#     "data": {
#         "id": "1",
#         "type": "posts"
#         "attributes": {
#             "title": "JSON API paints my bikeshed!"
#         },
#         "relationships": {
#             "author": {
#                 "links": {
#                     "related": "/authors/9"
#                 }
#             },
#             "comments": {
#                 "links": {
#                     "related": "/posts/1/comments/"
#                 }
#                 "data": [
#                     {"id": 5, "type": "comments"},
#                     {"id": 12, "type": "comments"}
#                 ],
#             }
#         },
#     }
# }

Error formatting

Schema.load and Schema.validate will return JSON API-formatted Error objects.

from marshmallow import validate
from marshmallow_jsonapi import Schema, fields

class AuthorSchema(Schema):
    id = fields.Str(dump_only=True)
    first_name = fields.Str(required=True)
    last_name = fields.Str(required=True)
    password = fields.Str(load_only=True, validate=validate.Length(6))
    twitter = fields.Str()

    class Meta:
        type_ = 'people'

schema = AuthorSchema()
schema.validate({'first_name': 'Dan', 'password': 'short'})
# {
#     "errors": [
#         {
#             "detail": "Shorter than minimum length 6.",
#             "source": {"pointer": "/data/attributes/password"}
#         },
#         {
#             "detail": "Missing data for required field.",
#             "source": {"pointer": "/data/attributes/last_name"}
#         }
#     ]
# }

Inflection

You can optionally specify a function to transform attribute names. For example, you may decide to follow JSON API’s recommendation to use “dasherized” names.

from marshmallow_jsonapi import Schema, fields

def dasherize(text):
    return text.replace('_', '-')

class AuthorSchema(Schema):
    id = fields.Str(dump_only=True)
    first_name = fields.Str(required=True)
    last_name = fields.Str(required=True)

    class Meta:
        type_ = 'people'
        inflect = dasherize

result = AuthorSchema().dump(author)
result.data
# {
#     'data': {
#         'id': '9',
#         'type': 'people',
#         'attributes': {
#             'first-name': 'Dan',
#             'last-name': 'Gebhardt'
#         }
#     }
# }

Flask integration

Marshmallow-jsonapi includes optional utilities to integrate with Flask.

For example, the HyperlinkRelated field in the marshmallow_jsonapi.flask module allows you to pass an endpoint name instead of a path template.

The above schema could be rewritten in a Flask application like so:

from marshmallow_jsonapi import Schema, fields
from marshmallow_jsonapi.flask import HyperlinkRelated

class PostSchema(Schema):
    id = fields.Str(dump_only=True)
    title = fields.Str()

    author = HyperlinkRelated(
        # Flask endpoint name, passed to url_for
        endpoint='author_detail',
        url_kwargs={'author_id': '<author.id>'},
    )

    comments = HyperlinkRelated(
        endpoint='posts_comments',
        url_kwargs={'post_id': '<id>'},
        # Include resource linkage
        many=True, include_data=True,
        type_='comments'
    )

    class Meta:
        type_ = 'posts'

See here for a full example.

Installation

pip install marshmallow-jsonapi

Documentation

Full documentation is available at https://marshmallow-jsonapi.readthedocs.org/.

Requirements

  • Python >= 2.7 or >= 3.3

License

MIT licensed. See the bundled LICENSE file for more details.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

marshmallow-jsonapi-0.2.0.tar.gz (15.9 kB view hashes)

Uploaded Source

Built Distribution

marshmallow_jsonapi-0.2.0-py2.py3-none-any.whl (12.2 kB view hashes)

Uploaded Python 2 Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page