Skip to content

Add a layered ViewSet API - #63

Draft
jgoclawski wants to merge 10 commits into
general_fixesfrom
api_layers_redesign
Draft

jgoclawski wants to merge 10 commits into
general_fixesfrom
api_layers_redesign

Conversation

@jgoclawski

@jgoclawski jgoclawski commented Oct 18, 2026 •

Copy link
Copy Markdown
Member

Summary

A new way to build JSON:API endpoints from small layers, next to the existing classes, which keep working unchanged.

A ViewSet declares a resource: schema, filter schema, allowed_actions, guards, object_permissions, middlewares and one data_service. A request goes through these layers in a fixed order:

  1. Allowed actions: actions the resource does not serve answer 405 before the request body is parsed. The default is empty, so a ViewSet that declares nothing serves nothing.
  2. Guards: request-level checks such as token authentication, run in list order before the body is parsed.
  3. Object permissions: row-level permission checks (flask_jsonapi.permissions.CheckObjectPermission), always the outermost data layer. None by default; a subclass can switch it off for another audience. On lists, the layer's filter restricts the query to objects the client may list (and may answer 403 for a scope the client named but may not list); if the per-object check still drops an object, the view logs a warning and hides the total, so a total never counts objects the client cannot see.
  4. Middlewares: optional business layers wrapping every call to the data service. Each receives inner, the rest of the chain, so it can act before and after the call.
  5. Data service: a repository or a use case. It is HTTP-agnostic and raises its own exceptions (ResourceNotFound, PermissionDenied, InvalidData, Conflict, Unavailable, ...), which the view translates to JSON:API errors in one place.

One vocabulary from declaration to repository: Actions.create/read/list/update/destroy map to create(data), read(id), list(filters, sorting, pagination) returning ListResult(items, total), update(resource, data), destroy(resource). Detail actions load the object once and hand it to update and destroy. Presentation work such as rendering belongs in the schema. Layers are instances created once and shared by all requests, so they must keep no per-request state.

Documentation: a guide with how-to recipes and a full, tested example in docs/guide.rst; reference pages docs/layers.rst, docs/view_sets.rst, docs/views.rst; a migration guide in docs/migration.rst.

Main additions

  • flask_jsonapi.ViewSet, DetailView, ListView; Actions.list (Actions.read_many kept as an alias)
  • flask_jsonapi.guards.Guard
  • flask_jsonapi.permissions.ObjectPermissions, CheckObjectPermission
  • flask_jsonapi.middlewares: Middleware, build_pipeline, CheckRequiredListFilters
  • flask_jsonapi.data_services: DataService, ListResult, its exceptions, LegacyRepositoryAdapter, and data_services.sqlalchemy_repositories.SqlAlchemyModelRepository
  • New HTTP exceptions: Unauthorized, UnprocessableEntity, ServiceUnavailable

Changes for existing code (no migration needed)

  • Every error leaving a flask-jsonapi view, legacy views included, is a JSON:API error document. Unexpected exceptions are logged with logger.exception and answered with a generic 500 without internal details; flask.abort() responses are converted too.
  • Flask app error handlers (@app.errorhandler) no longer run for exceptions raised inside flask-jsonapi views, and in testing mode such exceptions no longer propagate to the test client.
  • HEAD is served by the GET handler; a PATCH with a wrong resource type answers 409.
  • Empty detail and source are omitted from error objects; exception classes accept keyword arguments, and every positional form that worked before still works.
  • The legacy view and repository classes are marked deprecated in the docs (no runtime warnings).

Testing

  • Unit tests for every layer, end-to-end tests through the Flask test client, and SQLite integration tests (one SELECT per PATCH, pagination totals that respect permission filters, legacy repositories through the adapter).
  • The guide's full example lives in docs/examples/full_example.py and every documented request and response is asserted by tests/test_docs_full_example.py.
  • 331 tests pass and every commit passes on its own; the new modules have full line coverage; flake8, isort and a warning-free Sphinx build are clean.
  • Also verified against a production service: its full existing test suite passes on this branch, and one of its modules was migrated to the new API with its access rules unchanged.

Builds on #62.

🤖 Generated with Claude Code

jgoclawski and others added 2 commits October 17, 2026 23:55
Positional forms from 1.4 keep working without warnings: services raise
ForbiddenError('...') in many places.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@jgoclawski
jgoclawski marked this pull request as draft October 18, 2026 09:13
jgoclawski and others added 8 commits October 18, 2026 22:54
Failed commits and flushes roll the session back before the error is
translated, so a scoped session stays usable after a Conflict.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Deprecation is documentation only: no runtime warnings, because existing
services declare hundreds of legacy ViewSets.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant