Skip to content

README.rst

Latest commit

 

History

History
195 lines (151 loc) · 7.44 KB

README.rst

File metadata and controls

195 lines (151 loc) · 7.44 KB

OpenSPP API V2

Production/Stable License: LGPL-3 OpenSPP/OpenSPP2

FastAPI-based REST API for social protection data exchange. Exposes registrant, program, and membership data via OAuth 2.0 authenticated endpoints with consent-based access control. Never exposes database IDs; all identifiers use namespace URIs for global interoperability.

Key Capabilities

  • OAuth 2.0 Authentication: Client credentials flow with scrypt-hashed secrets, scoped access
  • Consent-Based Access Control: All reads require active consent, filtered by organization type
  • External Identifiers Only: Namespace URIs for lookups, vocabulary IDs for coded values
  • Source Tracking: Records data provenance per ADR-008
  • Extension Registry: Domain modules register custom fields via spp.api.extension
  • Batch Operations: Create/update multiple registrants per request

Key Models

Model Description
spp.api.client OAuth 2.0 credentials, organization verification
spp.api.client.scope Resource/action permissions
spp.api.path Endpoint configuration and filters
spp.api.path.filter Field-level filter configurations
spp.api.filter.preset Saved filter combinations
spp.api.extension Domain field registry
spp.consent.scope Resource types per consent

UI Location

Navigate to Registry > Configuration > API V2 for all API configuration. Available submenus:

  • API Clients - Manage OAuth credentials and organization verification
  • API Extensions - View registered custom field extensions
  • API Paths - Configure available endpoints and static filters
  • API Filters - Define queryable field filters per path
  • Filter Presets - Create named filter combinations

API Client Form Tabs:

  • Consent & Security - Consent requirements, legal basis, organization type verification
  • Scopes - Resource/action permissions and program restrictions
  • Description - Client documentation

API Extension Form Tabs:

  • Fields - Registered custom fields from domain modules
  • JSON Schema - Auto-generated schema for extension fields

API Path Form Tabs:

  • Filters - Field-level filter configurations (inline editable)
  • Presets - Saved filter combinations (inline editable)

Configuration

After installing:

  1. Navigate to Registry > Configuration > API V2 > API Clients
  2. Create a new client, assign organization and organization type
  3. Click Verify Organization Type (requires Manager role)
  4. Click Regenerate Secret to view OAuth credentials
  5. Configure scopes via Scopes stat button or Scopes tab

API endpoints available at /api/v2/ (token endpoint: /api/v2/token).

Security

Group Access
group_api_v2_viewer Read-only: all API configuration and consent
group_api_v2_officer Read/Write: all models (no create/delete), full CRUD on consent scopes
group_api_v2_manager Full CRUD: clients, scopes, paths, filters, presets, extensions; Read/Write/Create on consent (no delete)

Extension Points

  • Inherit spp.api.extension to register custom fields
  • Override _get_fastapi_routers() in fastapi.endpoint for custom endpoints

Dependencies

base, fastapi, spp_security, spp_registry, spp_consent, spp_vocabulary, spp_programs, spp_source_tracking

Table of contents

Changelog

19.0.2.0.0

  • Initial migration to OpenSPP2

Bug Tracker

Bugs are tracked on GitHub Issues. In case of trouble, please check there if your issue has already been reported. If you spotted it first, help us to smash it by providing a detailed and welcomed feedback.

Do not contact contributors directly about support or help with technical issues.

Credits

Authors

  • OpenSPP.org

Maintainers

Current maintainers:

jeremi gonzalesedwin1123 reichie020212 emjay0921

This module is part of the OpenSPP/OpenSPP2 project on GitHub.

You are welcome to contribute.