{"id":22093955,"url":"https://github.com/chebizarro/nostr-http-openapi","last_synced_at":"2026-03-19T23:01:38.792Z","repository":{"id":265812798,"uuid":"869323924","full_name":"chebizarro/nostr-http-openapi","owner":"chebizarro","description":"A collection of Open API 3.0 specs for Nostr related HTTP endpoints","archived":false,"fork":false,"pushed_at":"2024-10-10T08:38:17.000Z","size":8,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-02-01T22:27:35.062Z","etag":null,"topics":["blossom","nip-96","nostr","open-api-v3"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chebizarro.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-08T05:31:50.000Z","updated_at":"2024-10-10T08:38:20.000Z","dependencies_parsed_at":null,"dependency_job_id":"9b9a1ffe-6f3c-494e-987f-51ab14846f82","html_url":"https://github.com/chebizarro/nostr-http-openapi","commit_stats":null,"previous_names":["chebizarro/nostr-http-openapi"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chebizarro%2Fnostr-http-openapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chebizarro%2Fnostr-http-openapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chebizarro%2Fnostr-http-openapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chebizarro%2Fnostr-http-openapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chebizarro","download_url":"https://codeload.github.com/chebizarro/nostr-http-openapi/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245915727,"owners_count":20693378,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blossom","nip-96","nostr","open-api-v3"],"created_at":"2024-12-01T03:23:21.418Z","updated_at":"2026-01-06T09:38:37.377Z","avatar_url":"https://github.com/chebizarro.png","language":null,"funding_links":[],"categories":["Tools"],"sub_categories":[],"readme":"# Nostr-Related HTTP Server Endpoints\n\nThis repository contains **validated and complete** OpenAPI specifications for Nostr-related HTTP server endpoints:\n\n## File Storage Protocols\n\n1. **Blossom API** (`blossom/blossom.yaml`): Complete Blossom protocol (BUD-01 through BUD-10) with all mandatory and optional features including media optimization, payment flows, and content reporting.\n2. **NIP-96 File Storage API** (`nip96/nip96.yaml`): Full NIP-96 specification with NIP-98 authorization for file uploads, downloads, and management.\n\n## Core Nostr HTTP Protocols\n\n3. **NIP-05 Identifier Lookup** (`nip05/nip05.yaml`): DNS-based internet identifier to Nostr pubkey mapping via `/.well-known/nostr.json`\n4. **NIP-11 Relay Information** (`nip11/nip11.yaml`): Relay metadata and capabilities discovery document\n5. **NIP-57 Lightning Zaps** (`nip57/nip57.yaml`): LNURL pay integration with Nostr zap requests and receipts\n6. **NIP-86 Relay Management** (`nip86/nip86.yaml`): JSON-RPC relay administration API with NIP-98 authentication\n\nAll specifications are **100% protocol-compliant** and ready for production code generation.\n\n## ✅ Validation Status\n\nAll OpenAPI specs have been validated and tested:\n- ✅ **Blossom API**: Valid OpenAPI 3.0 schema\n- ✅ **NIP-96 API**: Valid OpenAPI 3.0 schema\n- ✅ **NIP-05 API**: Valid OpenAPI 3.0 schema\n- ✅ **NIP-11 API**: Valid OpenAPI 3.0 schema\n- ✅ **NIP-57 API**: Valid OpenAPI 3.0 schema\n- ✅ **NIP-86 API**: Valid OpenAPI 3.0 schema\n- ✅ All endpoints match protocol requirements\n- ✅ Code generation tested across multiple languages\n\n## Requirements\n\n- **OpenAPI Generator**: The primary tool used for generating code in different languages from OpenAPI specifications. You can install it via [Homebrew](https://brew.sh/) or use it directly via Docker.\n\n### Installing OpenAPI Generator\n\n- **Using Homebrew** (macOS):\n  \n  ```bash\n  brew install openapi-generator\n  ```\n\n- **Using Docker**:\n  \n  ```bash\n  docker pull openapitools/openapi-generator-cli\n  ```\n\nSee the [OpenAPI Generator Docs](https://openapi-generator.tech/docs/installation) for more installation options.\n\n## Testing \u0026 Validation\n\n### Quick Validation\n\n```bash\n# Install dependencies\nnpm install\n\n# Run automated validation\nnpm run validate\n\n# Or validate individual specs\nnpm run validate:blossom\nnpm run validate:nip96\n```\n\n### Manual Testing\n\nUse online tools for instant validation:\n- **Swagger Editor**: https://editor.swagger.io/ (drag \u0026 drop YAML files)\n- **Redocly**: Interactive API documentation and validation\n\n### Interactive Documentation\n\nPreview beautiful, interactive API docs locally:\n```bash\nnpm run preview:blossom\nnpm run preview:nip96\n# Opens in browser at http://localhost:8080\n```\n\nSee **[TESTING.md](TESTING.md)** for comprehensive testing guide including:\n- Multiple validation tools (Redocly CLI, openapi-generator, spectral)\n- CI/CD integration examples\n- Protocol-specific test cases\n- Troubleshooting common issues\n\n**📝 Note:** We use Redocly CLI (actively maintained) instead of the deprecated swagger-cli. See **[MIGRATION_TO_REDOCLY.md](MIGRATION_TO_REDOCLY.md)** for details.\n\n## Generating Code for the APIs\n\nYou can use **OpenAPI Generator** to generate server or client code for the **Nostr File Storage API** and **Blossom API** in multiple languages. Below are examples of how to generate code for some popular languages.\n\n### 1. Generate Go Code (Using `ogen-go` or OpenAPI Generator)\n\nThe repository includes OpenAPI v3 specifications for both APIs. To generate Go code for either of them, you can use the **`ogen-go`** tool (for Go only) or **OpenAPI Generator**.\n\n#### For Go (Using **`ogen-go`**)\n\n1. **Nostr File Storage API**:\n   \n   ```bash\n   ogen --target api/nostrfilestorage --package nostrfilestorage nostr-file-storage.yaml\n   ```\n\n2. **Blossom API**:\n   \n   ```bash\n   ogen --target api/blossom --package blossom blossom.yaml\n   ```\n\n#### For Go (Using **OpenAPI Generator**)\n\n```bash\nopenapi-generator-cli generate -i nostr-file-storage.yaml -g go-server -o api/nostrfilestorage\nopenapi-generator-cli generate -i blossom.yaml -g go-server -o api/blossom\n```\n\n### 2. Generate TypeScript Code\n\nTo generate TypeScript code, use the **`typescript-fetch`** or **`typescript-node`** generator options depending on whether you're creating a client or server.\n\n#### TypeScript Client (using Fetch API)\n\n```bash\nopenapi-generator-cli generate -i nostr-file-storage.yaml -g typescript-fetch -o typescript-client/nostrfilestorage\nopenapi-generator-cli generate -i blossom.yaml -g typescript-fetch -o typescript-client/blossom\n```\n\nThis will generate a TypeScript client that uses the Fetch API to interact with the Nostr File Storage and Blossom APIs.\n\n#### TypeScript Express Server\n\n```bash\nopenapi-generator-cli generate -i nostr-file-storage.yaml -g nodejs-express-server -o typescript-server/nostrfilestorage\nopenapi-generator-cli generate -i blossom.yaml -g nodejs-express-server -o typescript-server/blossom\n```\n\nThis will generate an **Express.js** server in TypeScript.\n\n### 3. Generate Rust Code\n\nTo generate Rust client or server code, use the **`rust`** or **`rust-server`** generator options.\n\n#### Rust Client\n\n```bash\nopenapi-generator-cli generate -i nostr-file-storage.yaml -g rust -o rust-client/nostrfilestorage\nopenapi-generator-cli generate -i blossom.yaml -g rust -o rust-client/blossom\n```\n\nThis will generate a Rust client that can be used to interact with the Nostr File Storage and Blossom APIs.\n\n#### Rust Server\n\n```bash\nopenapi-generator-cli generate -i nostr-file-storage.yaml -g rust-server -o rust-server/nostrfilestorage\nopenapi-generator-cli generate -i blossom.yaml -g rust-server -o rust-server/blossom\n```\n\nThis will generate a Rust server that can handle the API requests according to the OpenAPI specification.\n\n### 4. Generate Node.js Code\n\nTo generate Node.js client or server code, use the **`nodejs-express-server`** or **`javascript`** generator options.\n\n#### Node.js Express Server\n\n```bash\nopenapi-generator-cli generate -i nostr-file-storage.yaml -g nodejs-express-server -o node-server/nostrfilestorage\nopenapi-generator-cli generate -i blossom.yaml -g nodejs-express-server -o node-server/blossom\n```\n\nThis will generate a server based on **Express.js** for Node.js.\n\n#### Node.js Client\n\n```bash\nopenapi-generator-cli generate -i nostr-file-storage.yaml -g javascript -o node-client/nostrfilestorage\nopenapi-generator-cli generate -i blossom.yaml -g javascript -o node-client/blossom\n```\n\n### 5. Generate C# Code\n\nTo generate C# client or server code, use the `csharp` or `aspnetcore` generator options.\n\n#### C# Client\n\n```bash\nopenapi-generator-cli generate -i nostr-file-storage.yaml -g csharp -o csharp-client/nostrfilestorage\nopenapi-generator-cli generate -i blossom.yaml -g csharp -o csharp-client/blossom\n```\n\n#### ASP.NET Core Server\n\n```bash\nopenapi-generator-cli generate -i nostr-file-storage.yaml -g aspnetcore -o csharp-server/nostrfilestorage\nopenapi-generator-cli generate -i blossom.yaml -g aspnetcore -o csharp-server/blossom\n```\n\n### 6. Other Languages\n\nOpenAPI Generator supports many other languages. You can check the full list of supported generators [here](https://openapi-generator.tech/docs/generators).\n\nFor example, to generate PHP or Python code, you can use:\n\n- **PHP**:\n  \n  ```bash\n  openapi-generator-cli generate -i nostr-file-storage.yaml -g php -o php-client/nostrfilestorage\n  openapi-generator-cli generate -i blossom.yaml -g php -o php-client/blossom\n  ```\n\n- **Python**:\n  \n  ```bash\n  openapi-generator-cli generate -i nostr-file-storage.yaml -g python -o python-client/nostrfilestorage\n  openapi-generator-cli generate -i blossom.yaml -g python -o python-client/blossom\n  ```\n\n## Running the Generated Code\n\nEach language and framework will have its own way of running and testing the generated code. Typically, once the code is generated, follow these steps:\n\n1. **Install dependencies** (if needed):\n   - For **TypeScript**, run `npm install` or `yarn install`.\n   - For **Rust**, ensure you have the necessary Rust toolchain installed (`cargo`).\n   - For **Go**, make sure the `go.mod` file is correctly set up.\n\n2. **Implement the required handlers** for server code, or use the generated client to interact with the server.\n\n3. **Start the server** or run the client depending on the generated code structure.\n\nFor example, to run a TypeScript Node.js server, navigate to the generated server directory and run:\n\n```bash\nnpm start\n```\n\nSimilarly, for a Rust server:\n\n```bash\ncargo run\n```\n\n## Notes on NIP-96 and NIP-98\n\nThe **Nostr File Storage API** complies with NIP-96 and NIP-98, which deal with decentralized content storage and delegation. Make sure to handle the `.well-known/nostr/nip96.json` endpoint to configure the decentralized storage details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchebizarro%2Fnostr-http-openapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchebizarro%2Fnostr-http-openapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchebizarro%2Fnostr-http-openapi/lists"}