Internal vs External APIs

Internal APIs are used only by your team. External APIs are used by external developers. The audience and constraints are different, requiring different design approaches.

Internal APIs: Rapid Iteration

Internal APIs are consumed by your own front-end, mobile app, or services. You control both the API and consumers. Breaking changes aren't actually broken if everything deploys together.

You can iterate rapidly. Rename fields, change responses, restructure without breaking existing consumers. This freedom makes internal API development faster.

Versioning is optional. You can update all consumers and the API simultaneously. No need to support multiple versions.

External APIs: Stability and Contracts

External APIs are used by third parties. You don't control the consumers. Breaking changes break their applications. You must maintain backwards compatibility.

Versioning is required. Support multiple API versions for extended periods. Major version changes require long deprecation periods (6-12 months).

Documentation is critical. Without it, developers can't use your API. Comprehensive docs with examples are non-negotiable.

The Middle: Partner APIs

Partner APIs are shared with specific partners under agreement. More controlled than public, more formal than internal. SLAs might be negotiated. Deprecation policies are agreed upfront.

When Internal Becomes External

Your product grows. Partners want API access. Enterprises demand integration capabilities. What started as internal becomes external.

If you've designed internal APIs well, making them external is straightforward. Add documentation, versioning, formal authentication. The core API is ready.

API-First Design

Design the API before implementing. Think about resources, endpoints, data structures. What queries do clients need? What writes matter?

API-first design makes the implementation easier. The API defines the contract. Implementation conforms to it.

The BFF Pattern: Backend for Frontend

Backend for Frontend (BFF) is a dedicated API layer for a specific client. Your web app has one API. Your mobile app has a different API. Each BFF is optimized for its client.

Web BFF returns data structured for web UI. Mobile BFF returns minimal data (bandwidth matters). Third-party developers get a general-purpose API.

BFFs reduce over-fetching and simplify front-end logic. The front-end doesn't combine data from multiple endpoints. The BFF does it.

GraphQL for Internal APIs

GraphQL can work well for internal APIs when multiple front-ends have different data needs. A single GraphQL endpoint serves all, each client requests exactly what it needs.

For external APIs, GraphQL is less common. REST is more familiar to external developers. GraphQL adds learning curve and complexity.

Backwards Compatibility Strategies

Support old field names alongside new ones. Clients using old names still work. Add warnings in responses to migrate.

Never remove fields without deprecation. Deprecate for 6-12 months, then remove in a major version bump.

Preserve response structure. If you renamed a field, keep the old name pointing to the new data.

Designing for Internal Use

You can use unconventional designs. Use whatever is fastest to implement and understand. Snake_case, camelCase, custom conventions—consistency matters more than following standards.

Designing for External Use

Follow REST conventions. Use standard HTTP methods. Use sensible status codes. Use camelCase or snake_case consistently. Make it obvious and standard. External developers expect it.