| Metadata | Value |
|---|---|
| Source | Confluence - Standard for types of APIs |
| Status | Published |
| Last Synced | 2026-01-08 |
| Space | Architecture (ARCH) |
This software standard provides a comprehensive framework for designing, managing, and securing APIs to support collaboration and Planet future growth. It categorises APIs into three types: Partner APIs, Internal APIs, and Private APIs, each tailored to specific audiences and purposes.
By defining clear rules for each type, this standard ensures that APIs are built to meet the needs of their users while maintaining security, organisation, and ease of maintenance.
The standard covers essential aspects such as authentication, authorisation, versioning, documentation, and monitoring, providing guidelines to ensure robust security and operational efficiency. It emphasises the importance of an API-first approach using OpenAPI specifications to create consistent and reusable interfaces, enhancing integration across various platforms.
The goal of this software standard is to provide a structured framework for the development, management, and security of APIs within our organisation. By defining clear guidelines and best practices, this standard aims to ensure that APIs are designed to meet the needs of their users while maintaining robust security, operational efficiency, and ease of maintenance.
Applies to all APIs developed by Planet teams.
| Aspect | 🤝 Partner APIs | 🏠 Internal APIs | 🔒 Private APIs |
|---|---|---|---|
| 📘 Definition | APIs designed for external business partners to enable B2B integration and controlled external access. | APIs that expose a specific bounded context within an organisation, intended for use by other bounded contexts, including company products, with potential internet exposure to support internal cross-context integration. | APIs restricted to use within a single bounded context, not exposed to the internet, and not consumed by other internal products or bounded contexts. |
| 🧑💻 Audience | External business partners, such as third-party developers or organisations under contractual agreements. | Internal bounded contexts, including developers and products across the organisation that rely on the exposed bounded context, potentially spanning teams or services. | Developers within a specific bounded context, limiting usage to that context's internal components. |
| 🌐 Exposure | Externally accessible, typically over the internet, supported by robust public-facing infrastructure. | May be internet-facing to serve other bounded contexts (e.g., company products requiring external access such as UI products), but restricted to internal organisational use via security controls. | Confined to the internal network within a single bounded context, with no internet exposure or access from outside that context. |
| 📄 Contracts | Stable, well-defined contracts (e.g., OpenAPI specifications) due to external reliance, with careful change management. | Defined contracts to ensure consistency and interoperability across bounded contexts, with flexibility for internal coordination of changes. Typically, exposing a Canonical Data Model of the bounded context the API belongs to. | Less formal or fluid contracts, managed within a single bounded context, sufficient for internal consistency and maintenance. Prioritise ease of change to support bounded context evolution, avoiding disrupting other bounded contexts. |
| 🧪 Technology | Exposed by our API Gateway tool of choice (Kong). Should be designed using widely accepted technologies, formats and conventions. REST (preferred) and GraphQL (in the future). | Technologies aligned with organisational standards, supporting integration across bounded contexts and potential internet exposure. | Flexible technology choices tailored to the needs of a single bounded context, adhering to basic company requirements. |
| 🛡️ Security | Robust security measures, including authentication (e.g., OAuth, API keys), authorisation, rate limiting, quotas, usage plans, and encryption. | Security matching their exposure—strong authentication and authorisation (e.g., IAM, tokens) if internet-facing, or scope-based authentication if not, ensuring access is limited to authorised bounded contexts. | Reliance on scope-based authorisation within the bounded context, with minimal controls to restrict access to that context's components. |
| 🔢 Versioning | Breaking changes are NOT allowed. Strict versioning (e.g., semantic versioning in URLs or headers) for backward compatibility and partner change notifications. | The standard is strongly against breaking changes - acknowledging that extreme situations can demand desperate measures. Versioning to manage updates across bounded contexts, with internal coordination allowing more flexibility than Partner APIs. | Versioning is recommended but can be less enforced as the team sees fit, as long as it is sufficient for upgrades within a single bounded context. |
| 📝 Documentation | Comprehensive, publicly available documentation (public Developer portal) with examples and integration guides. Internally available documentation within the internal Developer Portal. | Internally available documentation within the internal Developer Portal. | Minimal, context-specific documentation, useful for onboarding and maintenance within the bounded context. Documentation is optionally available internally within the internal Developer Portal. |
| 📊 Monitoring | Extensive monitoring (e.g., usage, performance, errors) with analytics and alerting to meet service-level agreements (SLAs). | Monitoring focused on performance and reliability across bounded contexts, critical for system health, especially if internet-facing. | Compliance with the Observability standards in place. Basic monitoring capabilities for debugging and optimisation within the bounded context. |
| 🧭 Governance | Multiple stakeholders: Architecture team (standards), Platform engineering (infrastructure), Development teams (build/maintain), Product/Business/Legal (contracts/compliance). | Collaborative structure: Architecture team (cross-context standards), Platform engineering (tools/infrastructure), Development teams (implementation/monitoring). | Localised governance: Development team (implementation/maintenance), Architecture team (minimal oversight for alignment). |
Adopting an API-first approach involves prioritising the design and development of APIs before implementing other system components. This strategy ensures that APIs are treated as foundational elements, leading to consistent and reusable interfaces that facilitate seamless integration across various platforms and devices.
Implementing API versioning is a critical strategy to manage changes effectively, enhance interoperability, and minimise the risk of breaking existing integrations.
| 🤝 Partner APIs | 🏠 Internal APIs | 🔒 Private APIs |
|---|---|---|
| Stability is paramount: Updates must not disrupt partners' operations. Breaking changes should be introduced in a new version. | Flexibility with Caution: Internal APIs can adapt more rapidly, but manage changes to prevent cascading issues. | Simplicity in Versioning: Given the limited scope, versioning can be more straightforward. |
| Clear Communication: Comprehensive documentation and advance notifications about changes or deprecations. | Internal Communication: Clear documentation and change logs to inform internal teams. | Direct Communication: Close collaboration allows for agile adjustments. |
This standard should be followed in new solutions or updates to existing ones.
Recommendations:
| Code | Question | Answer |
|---|---|---|
| FAQ.1 | What's the main difference between the types of APIs? | APIs are categorised based on who uses them and how they're accessed: Partner (external companies), Internal (between teams/systems), Private (single bounded context). |
| FAQ.2 | How do I decide which type of API to build? | Ask: Who needs to use this API, and where will it be accessed? External company = Partner, Different teams/systems = Internal, Single bounded context = Private. |
| FAQ.3 | What is a bounded context? | A clear section of your system that handles a specific job with its own rules and data. Work with the architecture team to define these boundaries. |
| FAQ.4 | Why do internal APIs need strong security? | Internal APIs might be accessed over the internet by company products. Without strong security, external access could be compromised. |
| FAQ.5 | What happens if we need to change an API others are using? | Evolving APIs should always be done in a backwards-compatible way. Use versioning and communicate with consumers. |
| FAQ.6 | Why do UI products access internal APIs directly? | UI products are first-class citizens managed by our teams, allowing direct connections without strict partner rules while maintaining security. |
Legacy payment terminals that cannot directly interface with modern Partner APIs present challenges:
Modern payment terminals should integrate directly through the Partner API.
