diff --git a/.github/workflows/postman.yaml b/.github/workflows/postman.yaml index 842b908..e3b266e 100644 --- a/.github/workflows/postman.yaml +++ b/.github/workflows/postman.yaml @@ -2,95 +2,70 @@ name: Publish to Postman Workspace on: push: - branches: - - main + branches: [demo-main] pull_request: - branches: - - main + branches: [demo-main] workflow_dispatch: jobs: - quality-checks: - name: Validate API and Collections + postman: runs-on: ubuntu-latest - steps: - - name: Checkout repository - uses: actions/checkout@v4 + - uses: actions/checkout@v6 + + - run: curl -o- "https://dl-cli.pstmn.io/install/unix.sh" | sh - name: Set up Node.js - uses: actions/setup-node@v4 + uses: actions/setup-node@v6 with: - node-version: '>= 20.19.0' - cache: 'yarn' + node-version: "24" + cache: "npm" - name: Install dependencies - run: yarn install - - - name: Install Postman CLI - run: curl -o- "https://dl-cli.pstmn.io/install/unix.sh" | sh - - - name: Verify Postman CLI version - run: postman --version - - - name: Login to Postman - env: - POSTMAN_API_KEY: ${{ secrets.POSTMAN_API_KEY }} - run: postman login --with-api-key "$POSTMAN_API_KEY" - - - name: Run unit and integration tests - run: yarn test - - - name: Run Spectral linting on collections - run: yarn lint:collections + run: npm install - - name: Start API server + - name: Start server in background run: | - yarn start & - echo $! > server.pid - - - name: Wait for API readiness - run: | - for attempt in {1..30}; do - if curl -sSf http://localhost:3000/health >/dev/null; then - exit 0 - fi - if curl -sSf http://localhost:3000 >/dev/null; then - exit 0 + npm run dev & + echo $! > pidfile + # Wait for server to be ready (port 3000) + for i in {1..20}; do + if nc -z localhost 3000; then + echo "Server is up!" + break fi - sleep 1 + echo "Waiting for server..." + sleep 2 done - echo "API did not become ready in time." >&2 - exit 1 - - name: Run Postman collection tests - run: yarn test:api - - - name: Stop API server - if: always() + # Local collection run does not require Postman cloud login (see Postman CLI auth docs). + # This avoids "invalid API key" when secrets are unavailable (e.g. PRs from forks). + - name: Validate Collection run: | - if [ -f server.pid ]; then - kill $(cat server.pid) || true - rm server.pid - fi + postman collection run "postman/collections/Intergalactic Bank API" - - name: Show workspace configuration - if: github.event_name != 'pull_request' + - name: Push to Postman Cloud + if: github.event_name == 'push' + env: + POSTMAN_API_KEY: ${{ secrets.POSTMAN_API_KEY }} + # Optional: set repo variable POSTMAN_REGION to `eu` if you use EU data residency + POSTMAN_REGION: ${{ vars.POSTMAN_REGION }} run: | - echo "๐Ÿงฉ Workspace Configuration:" - cat .postman/config.json - echo "" - echo "๐Ÿ“ Collections to sync:" - ls -la postman/collections/ - echo "" - echo "๐ŸŒ Environments to sync:" - ls -la postman/environments/ - - - name: Push workspace to Postman - run: postman workspace push -y - - - name: Confirm sync success - if: github.event_name != 'pull_request' + if [ -z "${POSTMAN_API_KEY}" ]; then + echo "::error::POSTMAN_API_KEY is empty. Add it under Settings โ†’ Secrets and variables โ†’ Actions." + echo "Secrets are not passed to workflows for pull_request events opened from repository forks." + exit 1 + fi + if [ -n "${POSTMAN_REGION}" ]; then + postman login --with-api-key "$POSTMAN_API_KEY" --region "$POSTMAN_REGION" + else + postman login --with-api-key "$POSTMAN_API_KEY" + fi + postman workspace push -y + - name: Stop server + if: always() run: | - echo "โœ… Workspace successfully synced!" - echo "๐ŸŒ View your workspace at: https://web.postman.co/workspace/a6c44822-f001-4728-b0d4-5a1917289054" + if [ -f pidfile ]; then + kill $(cat pidfile) || true + rm pidfile + fi diff --git a/.husky/pre-commit b/.husky/pre-commit index 5c48f8c..6978d2f 100755 --- a/.husky/pre-commit +++ b/.husky/pre-commit @@ -1,45 +1,5 @@ #!/usr/bin/env sh . "$(dirname -- "$0")/_/husky.sh" -echo "๐Ÿ” Running linter on staged files..." -npx lint-staged - -echo "๐Ÿงช Running tests..." -npm test - -# Run Spectral linting on Postman collections if they changed -if git diff --cached --name-only | grep -qE "postman/collections/"; then - echo "๐Ÿ“‹ Linting Postman collections with Spectral..." - node .spectral/lint-with-names.js - - if [ $? -ne 0 ]; then - echo "โŒ Spectral linting failed for Postman collections" - exit 1 - fi - - echo "โœ… Postman collection linting passed!" -fi - -# Run Postman tests only if Postman collection files changed -if git diff --cached --name-only | grep -qE "postman/"; then - echo "๐Ÿ“ฌ Postman collection changed - Running Postman tests..." - - # Run all collections in postman/collections/ - for collection in postman/collections/*.postman_collection.json; do - if [ -f "$collection" ]; then - echo " โ†’ Running: $(basename "$collection")" - postman collection run "$collection" - - if [ $? -ne 0 ]; then - echo "โŒ Postman collection failed: $collection" - exit 1 - fi - fi - done - - echo "โœ… All Postman collections passed!" -else - echo "โญ๏ธ No Postman collection changes detected, skipping Postman tests" -fi - -echo "โœ… All pre-commit checks passed!" +# Pre-commit hooks disabled (no-op). Restore previous behavior from git history if needed. +exit 0 diff --git a/.postman/resources.yaml b/.postman/resources.yaml new file mode 100644 index 0000000..891c3ca --- /dev/null +++ b/.postman/resources.yaml @@ -0,0 +1,7 @@ +# Use this workspace to collaborate +workspace: + id: "" + +localResources: + specs: + - ../openapi/openapi.yaml diff --git a/openapi/.openapi-generator-ignore b/openapi/.openapi-generator-ignore deleted file mode 100644 index 650edf4..0000000 --- a/openapi/.openapi-generator-ignore +++ /dev/null @@ -1,23 +0,0 @@ -# OpenAPI Generator Ignore File -# Files to ignore when generating code from openapi.yaml - -# Don't overwrite these files -README.md -package.json -.gitignore -.env - -# Don't generate documentation (we have custom docs) -docs/** - -# Keep our custom implementation -src/** - -# Keep our tests -tests/** - -# Keep config files -.eslintrc.js -.prettierrc -tsconfig.json - diff --git a/openapi/OPENAPI.md b/openapi/OPENAPI.md deleted file mode 100644 index 11ca40c..0000000 --- a/openapi/OPENAPI.md +++ /dev/null @@ -1,352 +0,0 @@ -# ๐Ÿ“˜ OpenAPI Specification - -This project includes a complete OpenAPI 3.0 specification for the Intergalactic Bank API. - -## ๐Ÿ“„ Files - -- **`openapi.yaml`** - OpenAPI 3.0 specification in YAML format - -## ๐Ÿ” What's Included - -The OpenAPI specification includes: - -### โœ… Complete API Documentation -- All endpoints (Admin, Accounts, Transactions) -- Request/response schemas with validation rules -- Detailed descriptions for all operations -- Multiple examples for each endpoint -- Error responses with status codes - -### ๐Ÿ” Security Definitions -- API key authentication scheme -- Admin permission requirements -- Rate limiting documentation - -### ๐Ÿ“Š Schemas -- **Account** - Account object with all properties -- **Transaction** - Transaction object with validation -- **Error** - Standardized error response format -- **Request Models** - Create and update request bodies - -### ๐ŸŽฏ Features -- Multiple server configurations (local, production, demo) -- Enum validation for currencies -- Date format specifications -- Numeric constraints (min/max values) -- Required vs optional fields -- Default values - -## ๐Ÿš€ Using the OpenAPI Spec - -### Viewing the Documentation - -#### Option 1: Swagger UI (Local) -```bash -# Using npx (no installation needed) -npx swagger-ui-watcher openapi.yaml -``` - -Then open: http://localhost:8080 - -#### Option 2: Swagger Editor Online -1. Go to https://editor.swagger.io/ -2. File โ†’ Import File -3. Select `openapi.yaml` - -#### Option 3: VS Code Extension -Install "OpenAPI (Swagger) Editor" extension and open `openapi.yaml` - -### Generating Client SDKs - -Use the OpenAPI Generator to create client libraries: - -```bash -# Install OpenAPI Generator -npm install -g @openapitools/openapi-generator-cli - -# Generate JavaScript client -openapi-generator-cli generate \ - -i openapi.yaml \ - -g javascript \ - -o ./client-sdk/javascript - -# Generate Python client -openapi-generator-cli generate \ - -i openapi.yaml \ - -g python \ - -o ./client-sdk/python - -# Generate TypeScript client -openapi-generator-cli generate \ - -i openapi.yaml \ - -g typescript-axios \ - -o ./client-sdk/typescript -``` - -### Generating Server Stubs - -Generate server boilerplate in various languages: - -```bash -# Generate Node.js Express server -openapi-generator-cli generate \ - -i openapi.yaml \ - -g nodejs-express-server \ - -o ./generated-server - -# Generate Python Flask server -openapi-generator-cli generate \ - -i openapi.yaml \ - -g python-flask \ - -o ./generated-server-python -``` - -### API Testing with OpenAPI - -#### Using Postman -1. Import `openapi.yaml` into Postman -2. Postman will automatically create a collection -3. Configure authentication and environment variables -4. Run requests directly - -#### Using Insomnia -1. Create โ†’ Import from โ†’ File -2. Select `openapi.yaml` -3. All endpoints will be imported - -#### Using curl with examples -The spec includes examples that can be used with curl: - -```bash -# Generate API key -curl http://localhost:3000/api/v1/auth - -# List accounts -curl -H "x-api-key: 1234" \ - http://localhost:3000/api/v1/accounts - -# Create account -curl -X POST http://localhost:3000/api/v1/accounts \ - -H "Content-Type: application/json" \ - -H "x-api-key: 1234" \ - -d '{ - "owner": "John Doe", - "balance": 1000, - "currency": "COSMIC_COINS" - }' -``` - -### Contract Testing - -Use the OpenAPI spec for contract testing: - -```bash -# Install Dredd -npm install -g dredd - -# Run contract tests -dredd openapi.yaml http://localhost:3000 -``` - -### Mock Server - -Create a mock server from the OpenAPI spec: - -```bash -# Using Prism -npm install -g @stoplight/prism-cli - -# Start mock server -prism mock openapi.yaml - -# Mock server will run on http://127.0.0.1:4010 -``` - -## ๐Ÿ“š OpenAPI Features Used - -### Path Parameters -```yaml -/api/v1/accounts/{accountId}: - parameters: - - name: accountId - in: path - required: true -``` - -### Query Parameters -```yaml -parameters: - - name: owner - in: query - required: false - schema: - type: string -``` - -### Request Bodies -```yaml -requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/CreateAccountRequest' -``` - -### Response Headers -```yaml -headers: - X-RateLimit-Limit: - description: Rate limit information - schema: - type: integer -``` - -### Reusable Components -```yaml -components: - schemas: - Account: - type: object - properties: - accountId: - type: string -``` - -### Multiple Examples -```yaml -examples: - transfer: - summary: Transfer between accounts - value: { ... } - deposit: - summary: Deposit to account - value: { ... } -``` - -## ๐Ÿ”ง Validation Rules - -The OpenAPI spec includes comprehensive validation: - -### String Validation -- `minLength`: Minimum string length -- `maxLength`: Maximum string length -- `pattern`: Regex patterns -- `enum`: Allowed values - -### Number Validation -- `minimum`: Minimum value -- `maximum`: Maximum value -- `exclusiveMinimum`: Greater than (not equal) -- `exclusiveMaximum`: Less than (not equal) - -### Object Validation -- `required`: Required properties -- `additionalProperties`: Allow extra properties -- `properties`: Define object structure - -### Array Validation -- `items`: Array item schema -- `minItems`: Minimum array length -- `maxItems`: Maximum array length - -## ๐ŸŽจ Customization - -### Updating Servers -Edit the `servers` section in `openapi.yaml`: - -```yaml -servers: - - url: https://api.yourcompany.com - description: Production - - url: https://staging-api.yourcompany.com - description: Staging -``` - -### Adding Custom Headers -Add to `components/headers`: - -```yaml -X-Custom-Header: - description: Your custom header - schema: - type: string -``` - -### Extending Schemas -Add new schemas or properties: - -```yaml -components: - schemas: - CustomModel: - type: object - properties: - field1: - type: string -``` - -## ๐Ÿ“Š Validation Tools - -### Validate the OpenAPI Spec - -```bash -# Using Swagger CLI -npm install -g @apidevtools/swagger-cli -swagger-cli validate openapi.yaml - -# Using OpenAPI CLI -npm install -g @redocly/cli -openapi lint openapi.yaml -``` - -### Check for Breaking Changes - -```bash -# Compare with previous version -openapi diff openapi-v1.yaml openapi-v2.yaml -``` - -## ๐ŸŒ Hosting Documentation - -### GitHub Pages -1. Generate static HTML: - ```bash - npx redoc-cli bundle openapi.yaml -o docs/index.html - ``` -2. Enable GitHub Pages on the `docs/` folder - -### Netlify/Vercel -Deploy Swagger UI or ReDoc with the spec file - -### Docker -```dockerfile -FROM swaggerapi/swagger-ui -COPY openapi.yaml /usr/share/nginx/html/openapi.yaml -ENV SWAGGER_JSON=/usr/share/nginx/html/openapi.yaml -``` - -## ๐Ÿ” Additional Resources - -- [OpenAPI 3.0 Specification](https://spec.openapis.org/oas/v3.0.3) -- [Swagger Editor](https://editor.swagger.io/) -- [OpenAPI Generator](https://openapi-generator.tech/) -- [Swagger UI](https://swagger.io/tools/swagger-ui/) -- [ReDoc](https://redocly.com/redoc/) -- [Stoplight Studio](https://stoplight.io/studio) - -## โœ… Compliance - -This OpenAPI specification is: -- โœ… OpenAPI 3.0.3 compliant -- โœ… Valid against JSON Schema -- โœ… Includes all required fields -- โœ… Uses standard HTTP status codes -- โœ… Follows REST best practices -- โœ… Includes comprehensive examples -- โœ… Documents all error responses - ---- - -**The OpenAPI spec is the single source of truth for the API contract! ๐Ÿ“˜** - diff --git a/openapi/openapi.yaml b/openapi/openapi.yaml deleted file mode 100644 index ce0b706..0000000 --- a/openapi/openapi.yaml +++ /dev/null @@ -1,760 +0,0 @@ -openapi: 3.1.0 -info: - title: Intergalactic Bank API - version: 1.0.0 - description: | - The Intergalactic Bank API makes it easy to manage transaction and account data. - Whether you're running an ATM for Astronauts or simply interested in keeping tabs on - your Cosmic Coins, Intergalactic Bank has you covered with REST-based requests to make it happen. - - ## Features - - **Account Management**: Create, read, update, and delete bank accounts - - **Transaction Processing**: Transfer funds between accounts or deposit to accounts - - **Multiple Currencies**: Support for COSMIC_COINS, GALAXY_GOLD, and MOON_BUCKS - - **API Key Authentication**: Secure endpoints with API key validation - - **Rate Limiting**: 300 requests per minute per API key - - contact: - name: Intergalactic Bank Support - url: https://intergalacticbank.example.com/support - license: - name: ISC - url: https://opensource.org/licenses/ISC - -servers: - - url: http://localhost:3000 - description: Local development server - - url: https://api.intergalacticbank.example.com - description: Production server - - url: https://template.postman-echo.com - description: Demo server - -tags: - - name: Admin - description: Administrative operations including API key management - - name: Accounts - description: | - Account management operations. An account at the Intergalactic Bank allows you to store funds. - Use these endpoints to list, create, update, and delete accounts. - - name: Transactions - description: | - Transaction operations. A transaction records money moving in or out of an account. - Transactions at the Galactic Bank follow a blockchain-like approach. Once created, - they cannot be updated or deleted. - -security: - - ApiKeyAuth: [] - -paths: - /api/v1/auth: - get: - tags: - - Admin - summary: Generate API key - description: | - Generates a new API key for accessing the Intergalactic Bank APIsss. - This endpoint does not require authentication. - operationId: generateApiKey - security: [] - responses: - '200': - description: Successful API key generation - headers: - X-RateLimit-Limit: - $ref: '#/components/headers/X-RateLimit-Limit' - X-RateLimit-Remaining: - $ref: '#/components/headers/X-RateLimit-Remaining' - X-RateLimit-Reset: - $ref: '#/components/headers/X-RateLimit-Reset' - content: - application/json: - schema: - type: object - required: - - apiKey - properties: - apiKey: - type: string - description: The generated API key - example: "123456789" - '500': - $ref: '#/components/responses/InternalServerError' - - /api/v1/accounts: - get: - tags: - - Accounts - summary: List all accounts - description: | - Retrieves a list of all accounts at the Intergalactic Bank. - Optionally filter by owner name or creation date. - operationId: listAccounts - parameters: - - name: owner - in: query - description: Filter accounts by owner's full name - required: false - schema: - type: string - example: "Nova Newman" - - name: createdAt - in: query - description: Filter accounts by creation date (YYYY-MM-DD format) - required: false - schema: - type: string - format: date - example: "2023-04-10" - responses: - '200': - description: Successful response with list of accounts - headers: - X-RateLimit-Limit: - $ref: '#/components/headers/X-RateLimit-Limit' - X-RateLimit-Remaining: - $ref: '#/components/headers/X-RateLimit-Remaining' - X-RateLimit-Reset: - $ref: '#/components/headers/X-RateLimit-Reset' - content: - application/json: - schema: - type: object - required: - - accounts - properties: - accounts: - type: array - items: - $ref: '#/components/schemas/Account' - examples: - withResults: - summary: Accounts found - value: - accounts: - - accountId: "1" - owner: "Nova Newman" - createdAt: "2023-04-10" - balance: 10000 - currency: "COSMIC_COINS" - - accountId: "2" - owner: "Gary Galaxy" - createdAt: "2023-04-10" - balance: 237 - currency: "COSMIC_COINS" - noResults: - summary: No accounts found - value: - accounts: [] - '401': - $ref: '#/components/responses/Unauthorized' - '429': - $ref: '#/components/responses/RateLimitExceeded' - '500': - $ref: '#/components/responses/InternalServerError' - - post: - tags: - - Accounts - summary: Create new account - description: | - Creates a new account at the Intergalactic Bank. The account will be assigned a unique ID. - The currency cannot be changed once the account is created. - operationId: createAccount - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/CreateAccountRequest' - examples: - withBalance: - summary: Create account with initial balance - value: - owner: "Nova Newman" - balance: 500 - currency: "COSMIC_COINS" - withoutBalance: - summary: Create account with zero balance - value: - owner: "Luna Starlight" - currency: "GALAXY_GOLD" - responses: - '201': - description: Account created successfully - headers: - X-RateLimit-Limit: - $ref: '#/components/headers/X-RateLimit-Limit' - X-RateLimit-Remaining: - $ref: '#/components/headers/X-RateLimit-Remaining' - X-RateLimit-Reset: - $ref: '#/components/headers/X-RateLimit-Reset' - content: - application/json: - schema: - type: object - required: - - account - properties: - account: - type: object - required: - - accountId - properties: - accountId: - type: string - description: The unique identifier of the created account - example: - account: - accountId: "123" - '400': - $ref: '#/components/responses/ValidationError' - '401': - $ref: '#/components/responses/Unauthorized' - '429': - $ref: '#/components/responses/RateLimitExceeded' - '500': - $ref: '#/components/responses/InternalServerError' - - /api/v1/transactions: - get: - tags: - - Transactions - summary: List all transactions - description: | - Retrieves a list of transactions. Optionally filter by source account, - destination account, or creation date. - operationId: listTransactions - parameters: - - name: fromAccountId - in: query - description: Filter transactions by source account ID - required: false - schema: - type: string - example: "11111111" - - name: toAccountId - in: query - description: Filter transactions by destination account ID - required: false - schema: - type: string - example: "18974440" - - name: createdAt - in: query - description: Filter transactions by creation date (YYYY-MM-DD format) - required: false - schema: - type: string - format: date - example: "2024-01-10" - responses: - '200': - description: Successful response with list of transactions - headers: - X-RateLimit-Limit: - $ref: '#/components/headers/X-RateLimit-Limit' - X-RateLimit-Remaining: - $ref: '#/components/headers/X-RateLimit-Remaining' - X-RateLimit-Reset: - $ref: '#/components/headers/X-RateLimit-Reset' - content: - application/json: - schema: - type: object - required: - - transactions - properties: - transactions: - type: array - items: - $ref: '#/components/schemas/Transaction' - examples: - withResults: - summary: Transactions found - value: - transactions: - - transactionId: "1" - createdAt: "2024-01-10" - amount: 94857902 - currency: "COSMIC_COINS" - fromAccountId: "11111111" - toAccountId: "18974440" - - transactionId: "2" - createdAt: "2024-01-10" - amount: 10000 - currency: "COSMIC_COINS" - fromAccountId: "11111111" - toAccountId: "18974440" - noResults: - summary: No transactions found - value: - transactions: [] - '401': - $ref: '#/components/responses/Unauthorized' - '429': - $ref: '#/components/responses/RateLimitExceeded' - '500': - $ref: '#/components/responses/InternalServerError' - - post: - tags: - - Transactions - summary: Create new transaction - description: | - Creates a new transaction. There are two types of transactions: - - **Transfer**: Move funds between two accounts by providing valid account IDs - - **Deposit**: Add money to an account by using "0" as the fromAccountId - - **Important**: Transactions cannot be edited or deleted once created. - operationId: createTransaction - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/CreateTransactionRequest' - examples: - transfer: - summary: Transfer between accounts - value: - fromAccountId: "12345678" - toAccountId: "87654321" - amount: 10000 - currency: "COSMIC_COINS" - deposit: - summary: Deposit to account - value: - fromAccountId: "0" - toAccountId: "87654321" - amount: 10000 - currency: "COSMIC_COINS" - responses: - '201': - description: Transaction created successfully - headers: - X-RateLimit-Limit: - $ref: '#/components/headers/X-RateLimit-Limit' - X-RateLimit-Remaining: - $ref: '#/components/headers/X-RateLimit-Remaining' - X-RateLimit-Reset: - $ref: '#/components/headers/X-RateLimit-Reset' - content: - application/json: - schema: - type: object - required: - - transaction - properties: - transaction: - type: object - required: - - transactionId - properties: - transactionId: - type: string - description: The unique identifier of the created transaction - example: - transaction: - transactionId: "123" - '400': - $ref: '#/components/responses/ValidationError' - '401': - $ref: '#/components/responses/Unauthorized' - '403': - $ref: '#/components/responses/InsufficientFunds' - '404': - $ref: '#/components/responses/AccountNotFound' - '429': - $ref: '#/components/responses/RateLimitExceeded' - '500': - $ref: '#/components/responses/InternalServerError' - - /api/v1/transactions/{transactionId}: - get: - tags: - - Transactions - summary: Get transaction by ID - description: Retrieves detailed information about a specific transaction by its ID. - operationId: getTransaction - parameters: - - $ref: '#/components/parameters/TransactionId' - responses: - '200': - description: Transaction details retrieved successfully - headers: - X-RateLimit-Limit: - $ref: '#/components/headers/X-RateLimit-Limit' - X-RateLimit-Remaining: - $ref: '#/components/headers/X-RateLimit-Remaining' - X-RateLimit-Reset: - $ref: '#/components/headers/X-RateLimit-Reset' - content: - application/json: - schema: - type: object - required: - - transaction - properties: - transaction: - $ref: '#/components/schemas/Transaction' - example: - transaction: - transactionId: "1" - createdAt: "2024-01-10" - amount: 10000 - currency: "COSMIC_COINS" - fromAccountId: "11111111" - toAccountId: "22222222" - '401': - $ref: '#/components/responses/Unauthorized' - '404': - $ref: '#/components/responses/TransactionNotFound' - '429': - $ref: '#/components/responses/RateLimitExceeded' - '500': - $ref: '#/components/responses/InternalServerError' - -components: - securitySchemes: - ApiKeyAuth: - type: apiKey - in: header - name: x-api-key - description: | - API key for authentication. Include your API key in the `x-api-key` header. - Generate a new API key using the `/api/v1/auth` endpoint. - - Admin operations require the admin API key (default: "1234"). - - parameters: - AccountId: - name: accountId - in: path - required: true - description: The unique identifier of the account - schema: - type: string - example: "123" - - TransactionId: - name: transactionId - in: path - required: true - description: The unique identifier of the transaction - schema: - type: string - example: "1" - - headers: - X-RateLimit-Limit: - description: The maximum number of requests permitted per minute - schema: - type: integer - example: 300 - - X-RateLimit-Remaining: - description: The number of requests remaining in the current rate limit window - schema: - type: integer - example: 299 - - X-RateLimit-Reset: - description: The time at which the current rate limit window resets (UTC epoch seconds) - schema: - type: integer - example: 1678901234 - - schemas: - Account: - type: object - required: - - accountId - - owner - - createdAt - - balance - - currency - properties: - accountId: - type: string - description: Unique identifier for the account - example: "1" - owner: - type: string - description: Full name of the account owner - minLength: 1 - example: "Nova Newman" - createdAt: - type: string - format: date - description: Date the account was created (YYYY-MM-DD) - example: "2023-04-10" - balance: - type: number - format: double - description: Current account balance - minimum: 0 - example: 10000 - currency: - type: string - description: Currency type for the account - enum: - - COSMIC_COINS - - GALAXY_GOLD - - MOON_BUCKS - example: "COSMIC_COINS" - - CreateAccountRequest: - type: object - required: - - owner - - currency - properties: - owner: - type: string - description: Full name of the account owner - minLength: 1 - example: "Nova Newman" - balance: - type: number - format: double - description: Initial account balance (defaults to 0 if not provided) - minimum: 0 - default: 0 - example: 500 - currency: - type: string - description: Currency type for the account (cannot be changed after creation) - enum: - - COSMIC_COINS - - GALAXY_GOLD - - MOON_BUCKS - example: "COSMIC_COINS" - - UpdateAccountRequest: - type: object - required: - - owner - properties: - owner: - type: string - description: Updated full name of the account owner - minLength: 1 - example: "Nova Newman" - - Transaction: - type: object - required: - - transactionId - - createdAt - - amount - - currency - - fromAccountId - - toAccountId - properties: - transactionId: - type: string - description: Unique identifier for the transaction - example: "1" - createdAt: - type: string - format: date - description: Date the transaction was created (YYYY-MM-DD) - example: "2024-01-10" - amount: - type: number - format: double - description: Transaction amount - minimum: 0 - exclusiveMinimum: true - example: 10000 - currency: - type: string - description: Currency type for the transaction - enum: - - COSMIC_COINS - - GALAXY_GOLD - - MOON_BUCKS - example: "COSMIC_COINS" - fromAccountId: - type: string - description: Source account ID (use "0" for deposits from external source) - example: "11111111" - toAccountId: - type: string - description: Destination account ID - example: "22222222" - - CreateTransactionRequest: - type: object - required: - - fromAccountId - - toAccountId - - amount - - currency - properties: - fromAccountId: - type: string - description: Source account ID (use "0" for deposits from external source) - example: "12345678" - toAccountId: - type: string - description: Destination account ID - example: "87654321" - amount: - type: number - format: double - description: Transaction amount (must be positive) - minimum: 0 - exclusiveMinimum: true - example: 10000 - currency: - type: string - description: Currency type (must match account currencies) - enum: - - COSMIC_COINS - - GALAXY_GOLD - - MOON_BUCKS - example: "COSMIC_COINS" - - Error: - type: object - required: - - error - properties: - error: - type: object - required: - - name - - message - properties: - name: - type: string - description: Error type identifier - example: "validationError" - message: - type: string - description: Human-readable error message - example: "Owner name is required and must be a string" - - responses: - Unauthorized: - description: Authentication required or API key invalid - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - error: - name: "authenticationError" - message: "API key is required. Please provide an API key in the x-api-key header." - - Forbidden: - description: Insufficient permissions to perform this operation - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - examples: - adminRequired: - summary: Admin access required - value: - error: - name: "forbiddenError" - message: "You do not have permissions to perform this action. Admin access required." - accountPermission: - summary: Account permission denied - value: - error: - name: "forbiddenError" - message: "You do not have permissions to update this account." - - AccountNotFound: - description: The specified account does not exist - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - error: - name: "instanceNotFoundError" - message: "The specified account does not exist." - - TransactionNotFound: - description: The specified transaction does not exist - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - error: - name: "instanceNotFoundError" - message: "The specified transaction does not exist." - - ValidationError: - description: Request validation failed - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - examples: - missingField: - summary: Missing required field - value: - error: - name: "validationError" - message: "Owner name is required and must be a string" - invalidCurrency: - summary: Invalid currency - value: - error: - name: "validationError" - message: "Currency must be one of: COSMIC_COINS, GALAXY_GOLD, MOON_BUCKS" - negativeAmount: - summary: Invalid amount - value: - error: - name: "validationError" - message: "Amount must be a positive number" - - InsufficientFunds: - description: Insufficient funds to complete the transaction - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - error: - name: "txInsufficientFunds" - message: "Not enough funds in source account to complete transaction." - - RateLimitExceeded: - description: Too many requests - rate limit exceeded - headers: - X-RateLimit-Limit: - $ref: '#/components/headers/X-RateLimit-Limit' - X-RateLimit-Remaining: - schema: - type: integer - example: 0 - X-RateLimit-Reset: - $ref: '#/components/headers/X-RateLimit-Reset' - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - error: - name: "rateLimitExceeded" - message: "Too many requests. Maximum 300 requests per minute allowed." - - InternalServerError: - description: Internal server error - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - error: - name: "serverError" - message: "An unexpected error occurred" - diff --git a/postman/collections/Intergalactic Bank API/.resources/definition.yaml b/postman/collections/Intergalactic Bank API/.resources/definition.yaml new file mode 100644 index 0000000..2f5b718 --- /dev/null +++ b/postman/collections/Intergalactic Bank API/.resources/definition.yaml @@ -0,0 +1,8 @@ +$kind: collection +name: Intergalactic Bank API +description: API collection for the Intergalactic Bank - manage accounts, transactions, and more across the galaxy. +variables: + - key: baseUrl + value: 'http://localhost:3000' + - key: apiKey + value: '1234' diff --git a/postman/collections/Intergalactic Bank API/Accounts/.resources/definition.yaml b/postman/collections/Intergalactic Bank API/Accounts/.resources/definition.yaml new file mode 100644 index 0000000..7663f4d --- /dev/null +++ b/postman/collections/Intergalactic Bank API/Accounts/.resources/definition.yaml @@ -0,0 +1,3 @@ +$kind: collection +description: Endpoints for managing bank accounts - create, read, update, and delete accounts. +order: 2000 diff --git a/postman/collections/Intergalactic Bank API/Accounts/Create Account.request.yaml b/postman/collections/Intergalactic Bank API/Accounts/Create Account.request.yaml new file mode 100644 index 0000000..e6e05f8 --- /dev/null +++ b/postman/collections/Intergalactic Bank API/Accounts/Create Account.request.yaml @@ -0,0 +1,18 @@ +$kind: http-request +method: POST +url: '{{baseUrl}}/api/v1/accounts' +order: 3000 +headers: + - key: x-api-key + value: '{{apiKey}}' + - key: Content-Type + value: application/json +body: + type: json + content: |- + { + "owner": "John Doe", + "currency": "COSMIC_COINS", + "balance": 1000, + "accountType": "STANDARD" + } diff --git a/postman/collections/Intergalactic Bank API/Accounts/Delete Account.request.yaml b/postman/collections/Intergalactic Bank API/Accounts/Delete Account.request.yaml new file mode 100644 index 0000000..1ce3a83 --- /dev/null +++ b/postman/collections/Intergalactic Bank API/Accounts/Delete Account.request.yaml @@ -0,0 +1,11 @@ +$kind: http-request +method: DELETE +url: '{{baseUrl}}/api/v1/accounts/:id' +order: 5000 +headers: + - key: x-api-key + value: '{{apiKey}}' +pathVariables: + - key: id + value: '' + description: The account ID to soft-delete diff --git a/postman/collections/Intergalactic Bank API/Accounts/Get Account.request.yaml b/postman/collections/Intergalactic Bank API/Accounts/Get Account.request.yaml new file mode 100644 index 0000000..665ea48 --- /dev/null +++ b/postman/collections/Intergalactic Bank API/Accounts/Get Account.request.yaml @@ -0,0 +1,11 @@ +$kind: http-request +method: GET +url: '{{baseUrl}}/api/v1/accounts/:id' +order: 2000 +headers: + - key: x-api-key + value: '{{apiKey}}' +pathVariables: + - key: id + value: '' + description: The account ID diff --git a/postman/collections/Intergalactic Bank API/Accounts/List Accounts.request.yaml b/postman/collections/Intergalactic Bank API/Accounts/List Accounts.request.yaml new file mode 100644 index 0000000..b7b5a04 --- /dev/null +++ b/postman/collections/Intergalactic Bank API/Accounts/List Accounts.request.yaml @@ -0,0 +1,16 @@ +$kind: http-request +method: GET +url: '{{baseUrl}}/api/v1/accounts' +order: 1000 +headers: + - key: x-api-key + value: '{{apiKey}}' +queryParams: + - key: owner + value: '' + description: Filter by account owner name + disabled: true + - key: createdAt + value: '' + description: Filter by creation date + disabled: true diff --git a/postman/collections/Intergalactic Bank API/Accounts/Update Account.request.yaml b/postman/collections/Intergalactic Bank API/Accounts/Update Account.request.yaml new file mode 100644 index 0000000..b77c5e2 --- /dev/null +++ b/postman/collections/Intergalactic Bank API/Accounts/Update Account.request.yaml @@ -0,0 +1,20 @@ +$kind: http-request +method: PUT +url: '{{baseUrl}}/api/v1/accounts/:id' +order: 4000 +headers: + - key: x-api-key + value: '{{apiKey}}' + - key: Content-Type + value: application/json +pathVariables: + - key: id + value: '' + description: The account ID to update +body: + type: json + content: |- + { + "owner": "Jane Doe", + "accountType": "PREMIUM" + } diff --git a/postman/collections/Intergalactic Bank API/General/.resources/definition.yaml b/postman/collections/Intergalactic Bank API/General/.resources/definition.yaml new file mode 100644 index 0000000..b589174 --- /dev/null +++ b/postman/collections/Intergalactic Bank API/General/.resources/definition.yaml @@ -0,0 +1,3 @@ +$kind: collection +description: General endpoints including welcome, health check, and API key generation. +order: 1000 diff --git a/postman/collections/Intergalactic Bank API/General/Generate API Key.request.yaml b/postman/collections/Intergalactic Bank API/General/Generate API Key.request.yaml new file mode 100644 index 0000000..af96837 --- /dev/null +++ b/postman/collections/Intergalactic Bank API/General/Generate API Key.request.yaml @@ -0,0 +1,4 @@ +$kind: http-request +method: GET +url: '{{baseUrl}}/api/v1/auth' +order: 3000 diff --git a/postman/collections/Intergalactic Bank API/General/Health Check.request.yaml b/postman/collections/Intergalactic Bank API/General/Health Check.request.yaml new file mode 100644 index 0000000..1819c93 --- /dev/null +++ b/postman/collections/Intergalactic Bank API/General/Health Check.request.yaml @@ -0,0 +1,4 @@ +$kind: http-request +method: GET +url: '{{baseUrl}}/health' +order: 2000 diff --git a/postman/collections/Intergalactic Bank API/General/Welcome.request.yaml b/postman/collections/Intergalactic Bank API/General/Welcome.request.yaml new file mode 100644 index 0000000..33d7bb5 --- /dev/null +++ b/postman/collections/Intergalactic Bank API/General/Welcome.request.yaml @@ -0,0 +1,4 @@ +$kind: http-request +method: GET +url: '{{baseUrl}}/' +order: 1000 diff --git a/postman/collections/Intergalactic Bank API/Transactions/.resources/definition.yaml b/postman/collections/Intergalactic Bank API/Transactions/.resources/definition.yaml new file mode 100644 index 0000000..0996ed4 --- /dev/null +++ b/postman/collections/Intergalactic Bank API/Transactions/.resources/definition.yaml @@ -0,0 +1,3 @@ +$kind: collection +description: Endpoints for managing transactions - list, view, and create transfers and deposits. +order: 3000 diff --git a/postman/collections/Intergalactic Bank API/Transactions/Create Transaction.request.yaml b/postman/collections/Intergalactic Bank API/Transactions/Create Transaction.request.yaml new file mode 100644 index 0000000..c413427 --- /dev/null +++ b/postman/collections/Intergalactic Bank API/Transactions/Create Transaction.request.yaml @@ -0,0 +1,18 @@ +$kind: http-request +method: POST +url: '{{baseUrl}}/api/v1/transactions' +order: 3000 +headers: + - key: x-api-key + value: '{{apiKey}}' + - key: Content-Type + value: application/json +body: + type: json + content: |- + { + "fromAccountId": "source-account-id", + "toAccountId": "destination-account-id", + "amount": 500, + "currency": "COSMIC_COINS" + } diff --git a/postman/collections/Intergalactic Bank API/Transactions/Get Transaction.request.yaml b/postman/collections/Intergalactic Bank API/Transactions/Get Transaction.request.yaml new file mode 100644 index 0000000..477a117 --- /dev/null +++ b/postman/collections/Intergalactic Bank API/Transactions/Get Transaction.request.yaml @@ -0,0 +1,11 @@ +$kind: http-request +method: GET +url: '{{baseUrl}}/api/v1/transactions/:id' +order: 2000 +headers: + - key: x-api-key + value: '{{apiKey}}' +pathVariables: + - key: id + value: '' + description: The transaction ID diff --git a/postman/collections/Intergalactic Bank API/Transactions/List Transactions.request.yaml b/postman/collections/Intergalactic Bank API/Transactions/List Transactions.request.yaml new file mode 100644 index 0000000..fa9477c --- /dev/null +++ b/postman/collections/Intergalactic Bank API/Transactions/List Transactions.request.yaml @@ -0,0 +1,20 @@ +$kind: http-request +method: GET +url: '{{baseUrl}}/api/v1/transactions' +order: 1000 +headers: + - key: x-api-key + value: '{{apiKey}}' +queryParams: + - key: fromAccountId + value: '' + description: Filter by source account ID + disabled: true + - key: toAccountId + value: '' + description: Filter by destination account ID + disabled: true + - key: createdAt + value: '' + description: Filter by creation date + disabled: true diff --git a/postman/globals/workspace.globals.yaml b/postman/globals/workspace.globals.yaml new file mode 100644 index 0000000..e96c6d6 --- /dev/null +++ b/postman/globals/workspace.globals.yaml @@ -0,0 +1,2 @@ +name: Globals +values: []