Skip to content

API_LAYER.md

Latest commit

 

History

History
78 lines (57 loc) · 3.24 KB

API_LAYER.md

File metadata and controls

78 lines (57 loc) · 3.24 KB
Raw

API Layer

Field Value
Created 2026-07-10
Version 2.1
Version Notes v2 core routes.

Authentication

All /api/v2 endpoints require a Bearer JWT with full_api_access scope in production. The authentication implementation is omitted from this assessment clone to reduce noise; assume unauthenticated requests would receive 401 Unauthorized with {"error": "Invalid token: ..."}.

Webhooks use Stripe signature verification (see Webhooks section below).

/api/v2 — Core integration API

Activation codes

Method Path Controller Purpose
GET /api/v2/activation_codes/:id activation_codes#show Code details
POST /api/v2/activation_codes/claim activation_codes#claim Redeem code for enrollment
GET /api/v2/activation_codes/search activation_codes#search Search by code fragment or email
GET /api/v2/activation_code_orders activation_code_orders#index List orders
GET /api/v2/activation_code_orders/:id activation_code_orders#show Order details

Payments

Method Path Controller Purpose
GET /api/v2/payments payments#index List payments
GET /api/v2/payments/:id payments#show Payment details
POST /api/v2/payments payments#create Create Stripe PaymentIntent

User product access

Method Path Controller Purpose
POST /api/v2/user_product/access_status user_product#access_status Resolve paywall/access for one enrollment
POST /api/v2/user_product/show_statuses user_product#show_statuses Batch access status

Institutions & products

Method Path Controller Purpose
GET /api/v2/institution institution#index List institutions
GET /api/v2/institution/:id institution#show Institution details
PUT /api/v2/institution/retrieve_by_ids institution#retrieve_by_ids Bulk fetch by IDs
GET /api/v2/products/:id products#show Product details
GET /api/v2/payment_option payment_option#index Payment options
GET /api/v2/payment_setting/payment_setting_for_course payment_setting#payment_setting_for_course Course payment setting

Temp access

Method Path Controller Purpose
POST /api/v2/temp_access/initiate_time_trial temp_access#initiate_time_trial Start time-limited trial

Webhooks

Method Path Controller Purpose
POST /webhooks/v1/stripe_webhook/payment_events stripe_webhook#payment_events Stripe payment events (signature verified)

Conventions

  • Controllers inherit from Api::V2::ApplicationController (JWT enforced in production; omitted here).
  • Business logic lives in app/services/, not controllers.
  • Serializers in app/serializers/api/v2/ shape JSON responses.
  • Strong params on all mutation endpoints.

Adding a new endpoint (typical pattern)

  1. Add route in config/routes.rb
  2. Create or extend controller under app/controllers/api/v2/
  3. Implement service in app/services/
  4. Add serializer if response shape is non-trivial
  5. Document in this file