Swagger & API Tooling
The IoT.live platform provides Swagger/OpenAPI specifications and API tooling resources to help developers:
- Explore available APIs
- Understand request and response schemas
- Test API operations
- Build integrations
- Automate operational workflows
These resources are intended to simplify onboarding and accelerate integration development.
[IMAGE PLACEHOLDER: Swagger and API tooling overview]
Swagger/OpenAPI specification
The IoT.live API is documented using Swagger/OpenAPI definitions.
The Swagger specification includes:
- Available endpoints
- Request schemas
- Response schemas
- API groups
- Object definitions
- Operational models
The specification groups APIs into multiple service areas including:
- Connection APIs
- Campaign APIs
- Usage APIs
- Billing APIs
- Audit APIs
- Tagging APIs
- Provisioning APIs
[IMAGE PLACEHOLDER: Swagger API explorer]
Swagger host configuration
The Swagger specification currently references:
Documented API environments include:
API endpoint structure
Most API endpoints follow the structure:
Example:
This structure groups APIs by:
- Service domain
- Operational area
- Workflow category
Working with Swagger
Swagger tooling can be used to:
- Explore APIs interactively
- Validate request structures
- Review object schemas
- Test operational workflows
- Generate client SDKs
Typical developer workflows include:
- Review API schemas
- Build request payloads
- Test endpoints
- Validate responses
- Implement automation workflows
[IMAGE PLACEHOLDER: Swagger workflow example]
Common object definitions
The Swagger specification includes reusable object models such as:
- RequestAbstract
- ResponseAbstract
- Connection objects
- Campaign objects
- Export objects
- Usage objects
These shared schemas help standardise:
- Authentication
- Pagination
- Response handling
- Error processing
JSON request testing
The API is designed for:
- JSON POST requests
- HTTPS transport
- UTF-8 encoded payloads
Typical testing tools include:
- Swagger UI
- Postman
- cURL
- PowerShell
- Python scripts
- JavaScript clients
Example cURL request:
Multipart upload APIs
The platform documentation references multipart upload workflows for:
- Batch operations
- CSV-driven imports
- Large operational datasets
These APIs are commonly used for:
- Bulk provisioning
- Rate plan migrations
- Status changes
- Large inventory updates
[IMAGE PLACEHOLDER: Multipart upload workflow]
CSV-driven workflows
Several APIs support CSV-based operational processing.
Typical CSV workflows include:
- Bulk connection updates
- Customer association imports
- Tagging operations
- Campaign processing
Recommended practices include:
- Validating CSV formatting carefully
- Testing smaller datasets first
- Monitoring async processing
- Reviewing failed records
Incorrect CSV formatting may cause partial failures or rejected operations.
Async tooling workflows
Large operations may use:
- Async processing APIs
- Campaign monitoring APIs
- Export generation workflows
- Download/report APIs
Tooling support should include:
- Async status monitoring
- Retry handling
- Export tracking
- Operational logging
Recommended development workflow
Recommended onboarding process:
- Review Swagger definitions
- Authenticate successfully
- Test listConnections
- Validate response handling
- Implement pagination
- Build async workflow handling
- Add export and reporting support
[IMAGE PLACEHOLDER: Recommended API onboarding workflow]
Integration best practices
Recommended tooling and integration practices include:
- Use structured logging
- Track corrId consistently
- Validate all API result values
- Handle async workflows correctly
- Separate production and test environments
- Monitor failed operations carefully
Security considerations
Developer tooling may expose:
- API credentials
- Operational workflows
- Exported datasets
- Customer metadata
Recommended controls include:
- Secure credential storage
- Restricted API access
- Secure export handling
- Avoiding plaintext credentials in scripts
Never commit API credentials into source control repositories or shared automation scripts.