FlowOn API Structure
A FlowOn API is the top-level container for your API configuration. It defines a complete REST API that exposes Dynamics 365 data and operations to external applications.
API Definition
| Property | Required | Description |
|---|---|---|
| Name | Yes | Unique identifier for the API (e.g., "CustomerPortalAPI", "MobileAppAPI") |
| Project | Yes | The FlowOn Project this API belongs to |
| Description | No | Documentation explaining the API's purpose |
When you create a FlowOn API, a Draft version is automatically created. You work in the draft to configure your API, then publish versions when ready.
API Versioning
FlowOn API includes a comprehensive versioning system that allows you to manage API evolution while maintaining backward compatibility.
┌─────────────────────────────────────────────────────────────────────┐
│ API VERSIONING │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────┐ │
│ │ Create API │ │
│ │ "CustomerAPI" │ │
│ └────────┬────────┘ │
│ │ │
│ ▼ (auto-created) │
│ ┌─────────────────┐ │
│ │ DRAFT │ ◄─── Editable, work-in-progress │
│ │ │ │
│ └────────┬────────┘ │
│ │ │
│ │ Publish │
│ ▼ │
│ ┌─────────────────┐ │
│ │ Version 1.0 │ ◄─── Read-only, immutable │
│ │ (Major) │ │
│ └────────┬────────┘ │
│ │ │
│ ├──────────────────┐ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Version 1.1 │ │ Version 2.0 │ │
│ │ (Minor) │ │ (Major) │ │
│ └─────────────────┘ └─────────────────┘ │
│ │ │
│ │ Create Draft From │
│ ▼ │
│ ┌─────────────────┐ │
│ │ NEW DRAFT │ ◄─── Baseline versioning │
│ │ (based on 1.1) │ │
│ └─────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
Version Types
| Version Type | Description | Use Case |
|---|---|---|
| Draft | Editable, work-in-progress configuration | Active development and changes |
| Minor Version | Backward-compatible changes (e.g., 1.0 → 1.1) | Adding new endpoints, optional fields |
| Major Version | Breaking changes (e.g., 1.0 → 2.0) | Schema changes, removed endpoints |
Version Characteristics
| Characteristic | Draft | Published Version |
|---|---|---|
| Editable | Yes | No |
| Deployable | For testing only | Yes |
| Deletable | Yes | No |
| Baseline for new drafts | No | Yes |
Export
You can export your API configuration as an OpenAPI 3.0 specification for use with external tools, documentation, and client generation.
┌─────────────────────────────────────────────────────────────────────┐
│ API EXPORT │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────┐ │
│ │ FlowOn API │ │
│ │ Configuration │ │
│ └────────┬────────┘ │
│ │ │
│ │ Export │
│ ▼ │
│ ┌─────────────────┐ │
│ │ OpenAPI 3.0 │ │
│ │ Specification │ │
│ │ (.json) │ │
│ └────────┬────────┘ │
│ │ │
│ ├──────────────────────────────────────────┐ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Swagger UI │ │ Client SDK Gen │ │
│ │ Documentation │ │ (JS, C#, Python)│ │
│ └─────────────────┘ └─────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
Export Features
| Feature | Description |
|---|---|
| OpenAPI 3.0 Format | Industry-standard specification format |
| Version Included | API version embedded in the spec |
| Complete Schemas | All request/response models defined |
| Security Definitions | Authentication schemes documented |
| Endpoint Documentation | Tags and descriptions included |
Uses for Exported Specs
- API Documentation: Generate interactive documentation with Swagger UI or ReDoc
- Client Generation: Auto-generate SDKs for JavaScript, C#, Python, etc.
- API Gateway Configuration: Import into Azure API Management, AWS API Gateway
- Testing: Import into Postman or other API testing tools
- Validation: Validate requests/responses against the schema