https://github.com/melosso/portway
A friendly API gateway that simplifies your data integration. Built for Windows Server, available for Linux.
https://github.com/melosso/portway
api exact-globe iis-server proxy rest-api sql-server windows-server
Last synced: 6 months ago
JSON representation
A friendly API gateway that simplifies your data integration. Built for Windows Server, available for Linux.
- Host: GitHub
- URL: https://github.com/melosso/portway
- Owner: melosso
- License: other
- Created: 2025-04-15T20:23:43.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-07-25T16:08:25.000Z (6 months ago)
- Last Synced: 2025-07-25T18:59:03.461Z (6 months ago)
- Topics: api, exact-globe, iis-server, proxy, rest-api, sql-server, windows-server
- Language: C#
- Homepage: https://portway.melosso.com
- Size: 230 MB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 
Portway
[](LICENSE)
[](https://github.com/melosso/portway/commits/main)
[](https://github.com/melosso/portway/releases/latest)
**Portway** is a fast, lightweight API gateway optimized for Windows Server environments. It offers fine-grained access to SQL Server data and flexible service proxying — with full environment-awareness, secure auth, and automatic documentation.
Common applications that benefit from Portway are businesses looking to unlock their SQL Server data through modern APIs, companies modernizing legacy systems without costly rewrites, and organizations needing integration between internal services and external partners or software.
> 📍 [Landing Page](https://portway.melosso.com/) | 📜 [Documentation](https://portway-docs.melosso.com/) | 🧪 [Live Demo](https://portway-demo.melosso.com/)
A quick example to give you an idea of what this is all about:
## 🧩 Key Features
Portway is built with flexibility and control in mind. Whether you're proxying services or exposing SQL endpoints, Portway adapts to your infrastructure with secure, high-performance routing.
* **Multiple endpoint types**:
* **SQL Server (OData)** — direct CRUD access with schema-level control
* **Proxy** — forward to internal services; supports complex orchestration
* **File System** — read/write from local storage or cache
* **Webhook** — receive external calls and persist data to SQL
* **Auth system**: Token-based, with Azure Key Vault integration
* **Environment-aware routing**: Dev, staging, production — all isolated and configurable
* **Built-in Swagger**: Every endpoint is documented out-of-the-box
* **Comprehensive logging**: Request/response tracing, including live monitoring
* **Rate limiting**: Easy to configure; protects downstream systems
## ⚙️ Requirements
Before deploying Portway, make sure your environment meets the following requirements. These ensure full functionality across all features, especially SQL and authentication.
* [.NET 9+ Runtime](https://dotnet.microsoft.com/en-us/download/dotnet/9.0)
* IIS (production hosting) if hosting on Windows
* SQL Server access (for SQL endpoints)
* Local filesystem access for configuring/running the application
Ready to go? Then continue:
## 🚀 Getting Started
Follow these steps to get Portway up and running in your environment. Setup is fast and modular, making it easy to configure just what you need.
### 1. Download & Extract
Grab the [latest release](https://github.com/melosso/portway/releases) and extract it to your deployment folder.
### 2. Configure Your Environments
Define your server and environment settings to isolate dev/staging/prod as needed. These configs are used across endpoints and logging.
**`environments/settings.json`**
```json
{
"Environment": {
"ServerName": "localhost",
"AllowedEnvironments": ["prod", "dev"]
}
}
```
**`environments/prod/settings.json`**
```json
{
"ServerName": "localhost",
"ConnectionString": "Server=localhost;Database=prod;Trusted_Connection=True;Connection Timeout=5;TrustServerCertificate=true;"
}
```
### 3. Define Your Endpoints
Endpoints are configured as JSON files. Each type has its own directory and format, making them easy to manage and extend.
#### SQL Endpoint — `endpoints/SQL/Products/entity.json`
Exposes a SQL table with restricted columns and CRUD operations.
```json
{
"DatabaseObjectName": "Items",
"DatabaseSchema": "dbo",
"PrimaryKey": "ItemCode",
"AllowedColumns": ["ItemCode", "Description", "Assortment", "sysguid"],
"AllowedEnvironments": ["prod", "dev"]
}
```
#### Proxy Endpoint — `endpoints/Proxy/Accounts/entity.json`
Acts as a reverse proxy for internal services with full method control.
```json
{
"Url": "http://localhost:8020/services/Exact.Entity.REST.EG/Account",
"Methods": ["GET", "POST", "PUT", "DELETE", "MERGE"],
"AllowedEnvironments": ["prod", "dev"]
}
```
#### Composite Endpoint — `endpoints/Proxy/SalesOrder/entity.json`
Combines multiple calls into a single logical transaction for APIs requiring sequential or nested operations.
```json
{
"Type": "Composite",
"Url": "http://localhost:8020/services/Exact.Entity.REST.EG",
"Methods": ["POST"],
"CompositeConfig": {
"Name": "SalesOrder",
"Description": "Creates a complete sales order with multiple lines and header",
"Steps": [
{
"Name": "CreateOrderLines",
"Endpoint": "SalesOrderLine",
"Method": "POST",
"IsArray": true,
"ArrayProperty": "Lines",
"TemplateTransformations": {
"TransactionKey": "$guid"
}
},
{
"Name": "CreateOrderHeader",
"Endpoint": "SalesOrderHeader",
"Method": "POST",
"SourceProperty": "Header",
"TemplateTransformations": {
"TransactionKey": "$prev.CreateOrderLines.0.d.TransactionKey"
}
}
]
}
}
```
#### Files Endpoint — `endpoints/Files/Documents/entity.json`
Stores and serves files such as documents, images, or data files.
```json
{
"StorageType": "Local",
"BaseDirectory": "documents",
"AllowedExtensions": [".pdf", ".docx", ".xlsx", ".txt"],
"AllowedEnvironments": ["600", "700"]
}
```
#### Webhook Endpoint — `endpoints/Webhooks/entity.json`
Used for receiving and storing webhook payloads directly into your database.
```json
{
"DatabaseObjectName": "WebhookData",
"DatabaseSchema": "dbo",
"AllowedColumns": ["webhook1", "webhook2"]
}
```
### 4. Deploy
When you're ready to host your application in IIS, there are a few important things to keep in mind. If you plan to use a proxy, you'll need to configure the correct user identity to ensure everything works smoothly. Don't forget to double-check that your application pool and security settings are properly configured for production use - we're assuming you already have the fundamentals of website security covered.
> If you're using a **Proxy** setup, make sure you explicitly change the Application Identity. It's also worth taking some time to fine-tune your application pool and website settings to maximize uptime and strengthen your security policies. For additional guidance on security best practices, you might find [Security Headers by Probely](https://securityheaders.com/) helpful.
## 🔐 Auth & Security
### Token-Based Auth (Local)
Portway uses a lightweight token-based system for authentication. Tokens are machine-bound and stored securely on disk.
```bash
🗝️ Generated token for SERVER-1:
💾 Saved to /tokens/SERVER-1.txt
```
Include the token in request headers, with the Bearer prefix included:
```http
Authorization: Bearer YOUR_TOKEN
```
### Azure Key Vault Support
To centralize and secure configuration secrets, use Azure Key Vault. Portway can read secrets automatically by environment.
```powershell
$env:KEYVAULT_URI = "https://your-keyvault-name.vault.azure.net/"
```
Secrets format: `{env}-ConnectionString` and `{env}-ServerName`
## 📡 API Examples
Here are some common requests you'll make using Portway's endpoints.
### SQL
Query specific data with full OData support:
```http
GET /api/prod/Products?$filter=Assortment eq 'Books'&$select=ItemCode,Description
```
### Proxy
Forward calls to internal REST services:
```http
GET /api/prod/Accounts
POST /api/prod/Accounts
```
### Composite
Chain together multiple operations into one:
```http
POST /api/prod/composite/SalesOrder
Content-Type: application/json
{
"Header": {
"OrderDebtor": "60093",
"YourReference": "Connect async"
},
"Lines": [
{ "Itemcode": "BEK0001", "Quantity": 2, "Price": 0 },
{ "Itemcode": "BEK0002", "Quantity": 4, "Price": 0 }
]
}
```
### Files
Depending on your configuration, you could upload, list, and download files.
```http
POST /api/600/files/Documents
Authorization: Bearer YOUR_TOKEN
Content-Type: multipart/form-data
file=@report.pdf
```
List files:
```http
GET /api/600/files/Documents/list
Authorization: Bearer YOUR_TOKEN
```
Download a file:
```http
GET /api/600/files/Documents/abc123fileId
Authorization: Bearer YOUR_TOKEN
```
### Webhooks
Receive data from external services:
```http
POST /api/prod/webhook/webhook1
Content-Type: application/json
{
"eventType": "order.created",
"data": {
"orderId": "12345",
"customer": "ACME Corp"
}
}
```
You'll find comprehensive configuration examples in our [documentation page](https://portway-docs.melosso.com/).
## 📊 Logging & Monitoring
Portway provides visibility into its operations with detailed logs and health check endpoints.
* Logs stored under `/log` with daily rotation
* Auth logs included for auditing
* Health endpoints:
```http
GET /health
GET /health/live
GET /health/details
```
## 🤝 Credits
Thanks to the open source tools that make Portway possible:
* [ASP.NET Core](https://learn.microsoft.com/en-us/aspnet/core/)
* [DynamicODataToSQL](https://github.com/DynamicODataToSQL/DynamicODataToSQL)
* [Serilog](https://serilog.net/)
* [SQLite](https://www.sqlite.org/index.html)
## License
Portway is available under two licensing models:
* **Open Source (AGPL-3.0)** — Free for open source projects and personal use
* **Commercial License** — For commercial use with full transparency of the open source project
**Professional features** (multiple API-keys, priority support, guaranteed patches, DTAP environments) require a [commercial license](https://melosso.com/licensing/portway). Activation is simple with a license key from your account portal.
[Get your license →](https://melosso.com/licensing/portway)
## Contribution
Contributions are welcome. Please submit a PR if you'd like to help improve Portway. With your contributions, you may be eligible for a free license.