82 lines
4.1 KiB
Markdown
82 lines
4.1 KiB
Markdown
# emission-api-lib
|
|
|
|
`emission-api-lib` is the authoritative draft specification for provider-neutral emission calculation connectors.
|
|
|
|
The project defines a shared domain model, provider configuration format, provider capability vocabulary and validation artifacts for integrating multiple emission calculation providers through a stable connector layer.
|
|
|
|
## Status
|
|
|
|
Draft specification.
|
|
|
|
The specification is not stable yet. Breaking changes are expected until the first stable version is released.
|
|
|
|
## Purpose
|
|
|
|
Direct integrations between specialist applications and individual emission calculation APIs create long-term dependencies on provider-specific request formats, response formats and feature assumptions.
|
|
|
|
`emission-api-lib` defines a provider-neutral integration boundary. Applications should be able to express an emission calculation request in a stable domain format, while provider-specific mappings, capabilities and limitations are handled by connector implementations.
|
|
|
|
## Repository role
|
|
|
|
This repository is authoritative.
|
|
|
|
Language-specific repositories implement this specification, but do not define it.
|
|
|
|
- `emission-api-lib-java` is the Java reference implementation.
|
|
- `emission-api-lib-python` is the Python implementation.
|
|
- `emission-api-lib-php` is the PHP implementation.
|
|
|
|
All implementation repositories should link back to this repository.
|
|
|
|
## Provider scope
|
|
|
|
The specification is designed for multiple providers from the beginning.
|
|
|
|
A provider is described through XML configuration and machine-readable capability metadata. Implementations may use this information to validate requests, select providers, explain unsupported features and normalize responses.
|
|
|
|
## Specification artifacts
|
|
|
|
This repository may contain:
|
|
|
|
- `schema.json` for the shared domain model
|
|
- XSD files for provider XML validation
|
|
- provider XML examples
|
|
- normalized request and response examples
|
|
- provider capability definitions
|
|
- compatibility notes for language-specific implementations
|
|
|
|
## Initial domain
|
|
|
|
The first target domain is flight emission calculation.
|
|
|
|
The specification is expected to support provider capability discovery instead of assuming that every provider supports the same request structure, response structure or calculation options.
|
|
|
|
## Design principles
|
|
|
|
- Provider neutrality
|
|
- Multiple providers from the beginning
|
|
- Stable domain-level request and response concepts
|
|
- Explicit provider capabilities
|
|
- Configuration over hardcoded provider logic
|
|
- Replayability and auditability where supported
|
|
- Language implementations that follow the shared specification
|
|
|
|
## Supported providers
|
|
|
|
| Provider | API key requested | API key received | API tested | Supported |
|
|
| ------------------------------------------------- | ----------------- | ---------------- | ---------- | --------- |
|
|
| Atmosfair Webservice 5 | ☒ | | | |
|
|
| Google Travel Impact Model (various versions) | ☒ | | | |
|
|
| myclimate Flight Calculator V1 & V2 | ☒ | | | |
|
|
| myclimate Bulk Flight Calculator | ☒ | | | |
|
|
| GoClimate Flight Footprint | ☒ | | | |
|
|
| C-Level Carbon Balance API | ☒ | | | |
|
|
| KlimaLink API | ☒ | | | |
|
|
| KlimAPI Calculation & Compensation API (v1 & v2) | ☒ | | | |
|
|
| calco2la.to | ☑ | ☑ | ☑ | ☑ |
|
|
|
|
## License
|
|
|
|
The general specification repository is licensed under the GNU Affero General Public License, Version 3 or later.
|
|
|
|
Individual implementation repositories may use a different license if this improves integration and adoption. Each implementation repository must state its license clearly. |