Internal APIs, external APIs, integrations, and SDKs

Once software begins communicating with other software, APIs become more than technical interfaces. They become agreements between teams, systems, and sometimes entirely separate companies.

A product may depend on APIs operated by its own organization, APIs provided to outside developers, and APIs belonging to third-party services.

This lesson brings together the vocabulary used to describe those relationships: internal APIs, external APIs, third-party APIs, integrations, dependencies, contracts, documentation, versioning, and SDKs.

Internal and external APIs

Lesson 1 introduced the split. An internal APIConcept · lights on your mapinternal APIAn API designed for systems within the same organization: frontend to backend, dashboards to services. Usually the same technology as an external API; what differs is the audience, and how carefully changes must be managed. serves systems within the same organization, such as the coffee company’s frontend and support dashboard talking to its backend. An external APIConcept · lights on your mapexternal APIAn API offered to developers, partners, or customers outside the organization. Same technology as an internal API, but changes must be managed far more carefully; strangers depend on it. is offered to developers, partners, or customers outside it, the way a payment provider lets customer companies create charges and issue refunds.

The technology on the wire is usually identical: the same HTTP methods, URL paths, headers, JSON bodies, and status codes from the previous lessons. What changes is the audience: who depends on the API, and how carefully it must be changed.

Internal does not mean unimportant

A company generally has more control over an internal API than an external one, but that does not mean it can change the API carelessly.

An internal API may be used by:

• Several frontend applications
• Mobile apps
• Internal dashboards
• Data pipelines
• Other engineering teams
• Automated business processes

Changing one field or endpoint could break many systems within the company.

The difference is that the organization can usually coordinate the change directly with the affected teams, but with an external API, the company may not even know every developer or business relying on the existing behavior.

This makes external API changes especially sensitive.

What is a third-party API?

From the coffee company’s perspective, the payment provider’s API is a third-party APIConcept · lights on your mapthird-party APIAn API operated by another organization that your product uses: payments, maps, email, shipping, AI. The provider sees it as its external API; the customer sees the same interface as a third-party API it depends on..

A third-party API is an API operated by another organization that your product uses, and examples might include APIs for:

• Payments
• Maps
• Email
• Text messages
• Identity verification
• Shipping
• Weather
• Artificial intelligence

“External API” describes whom the provider makes the API available to. “Third-party API” describes the relationship from the customer’s perspective.

The payment provider sees its API as an external API, but the coffee company sees that same interface as a third-party API it depends on.

What is an integration?

An integrationConcept · lights on your mapintegrationThe working connection built between separate systems so they can exchange information or capabilities. It spans credentials, request formatting, error handling, monitoring, and updates. The API is the interface offered; the integration is the connection your team builds with it. is the connection created between separate systems so that they can exchange information or capabilities.

If the coffee backend sends payment requests to a payment provider, the team has built a payment integration.

An integration usually involves more than making one request. Engineers may need to:

• Obtain access credentials
• Read the provider’s documentation
• Format requests correctly
• Interpret responses
• Handle errors and timeouts
• Store provider identifiers
• Test unusual situations
• Monitor the connection
• Update the integration when the provider changes

The API is the interface being offered. The integration is the working connection your team builds using that interface.

An integration creates a dependency

Once a product relies on another system, that system becomes a dependencyConcept · lights on your mapdependencyRe-encounter from Module 3, sharpened: something your product relies on to function. A package runs as part of your software environment; a third-party service runs on another organization’s systems, where it can fail, slow down, or change behavior while your application is running..

Module 5 priced this cost already: when the payment provider is down, checkout is down. Module 3’s packages are dependencies too, and the split between them still matters. A package is borrowed code running inside your product; a third-party service is borrowed capability running on someone else’s systems. Both can fail, but they fail differently and are managed differently.

What is an API contract?

Lesson 1 called an API a contract and promised the details later in the module. This is later. An API contractConcept · lights on your mapAPI contractThe defined agreement describing how clients and an API are expected to communicate: endpoints, methods, required fields, data types, promised responses, errors, and limits. It lets teams build independently while maintaining shared expectations; breaking it breaks integrations. is the defined agreement describing how clients and an API are expected to communicate.

The contract may specify:

• Which endpoints exist
• Which HTTP methods they accept
• Which headers are required
• Which fields must appear in a request
• The expected data types and formats
• Which fields appear in the response
• Which status codes and errors may be returned
• How authentication works
• What each operation means
• Whether requests can safely be repeated
• Any usage or rate limits

Consider this request:

The contract might promise that a successful response will contain: { "order_id": 1042, "status": "confirmed" }

If the server suddenly changes "order_id" to "id" without warning, clients expecting the old field may stop working.

An API contract allows teams to build independently while maintaining shared expectations.

What is API documentation?

API documentationConcept · lights on your mapAPI documentationThe human-readable explanation of how to use an API: endpoints, request and response examples, required fields, authentication, errors, rate limits, and versions. It turns the API contract into something people can understand and implement. explains how developers should use an API.

Good documentation commonly includes:

• Available endpoints
• Request and response examples
• Required fields
• Authentication instructions
• Error codes
• Rate limits
• Explanations of important behavior
• Tutorials and common workflows
• Information about versions and deprecations

Developers often spend substantial time reading API documentation while building an integration. The documentation turns the API contract into something people can understand and implement.

For example, documentation might explain that payment amounts must be sent as integers representing cents: { "amount": 1450, "currency": "usd" }

Without that explanation, a developer might incorrectly assume that 1450 means $1,450 rather than $14.50.

What is API versioning?

APIs change over time.

A provider may need to add fields, change behavior, improve security, or replace an old design. But changing an API can break software that depends on the previous contract.

API versioningConcept · lights on your mapAPI versioningAllowing multiple versions of an API contract to exist (commonly /v1/ and /v2/ in the URL) so the API can evolve without forcing every client to change immediately. Old versions are eventually deprecated, beginning a migration period. allows multiple versions of an API contract to exist.

One common approach places the version in the URL: POST /v1/orders

A newer contract might be available at: POST /v2/orders

So existing clients can continue using version 1 while newer clients adopt version 2.

Versions can also be communicated through request headers, account settings, dates, or other mechanisms. The exact approach depends on the provider.

The central idea is: versioning allows an API to evolve without forcing every client to change immediately.

Deprecating an API version

Eventually the provider may deprecate the old version, a word Module 3 taught for packages: still working, no longer recommended, scheduled to go.

What is new at the API scale is that the clock runs between companies. The provider must balance its need to improve the API against its customers’ need for stability, and the customer must update its integration before the old version stops working.

What is an SDK?

SDKConcept · lights on your mapSDKSoftware Development Kit, a collection of code and tools that helps developers build with a platform or service. For an API, the SDK is a package providing friendly functions that construct requests, send them, and interpret responses. The API is the contract; the SDK is an optional tool for using it. stands for Software Development Kit.

An SDK is a collection of code and tools that helps developers build with a particular platform or service, and for an API it often provides friendly functions that construct requests, send them, interpret responses, and handle some repetitive details.

Compare the same action with and without one:

The SDK does not replace the API. It is a package that provides a convenient way to communicate with the remote API.

The relationship is: your code → SDK → API request → provider’s service

This connects Module 3’s packages with Module 6’s machine-to-machine communication.

The cost and value of an SDK

An SDK can make an integration faster and reduce mistakes.

It may provide:

• Convenient functions
• Built-in data types
• Authentication support
• Error handling
• Request retries
• Documentation inside the code editor
• Compatibility with the provider’s API

However, the SDK is also another dependency. The team must keep it updated and understand which API versions it supports.

Some developers choose to call an API directly when the SDK is outdated, unnecessarily large, or unavailable for their programming language.

The API is the underlying contract. The SDK is an optional tool for using it.

Seeing the full relationship

Imagine the coffee company integrates with a payment provider.

The payment provider publishes an external API.

From the coffee company’s perspective, it is a third-party API.

The coffee company builds an integration using the provider’s endpoints.

That integration makes the payment provider a dependency.

The API contract defines the required requests and promised responses.

The API documentation teaches the coffee company’s engineers how to use the contract.

The provider may offer an SDK that makes the requests easier to construct.

If the provider releases a new contract, API versioning allows the old and new designs to coexist temporarily, and eventually the old version may be deprecated, requiring the coffee company to update its integration.

All of these terms describe different parts of one relationship between software systems.

The mental model to remember

An internal API is intended for systems within the same organization.

An external API is offered to developers or systems outside the organization.

A third-party API is an outside organization’s API that your product uses.

An integration is the working connection built between systems.

A dependency is something your product relies on to function.

An API contract defines the requests an API accepts and the responses and behavior it promises.

API documentation explains how to use that contract.

API versioning allows the contract to evolve while preserving older integrations.

An SDK is a package of tools and code that makes an API easier to use.

You should now understand how APIs become long-term agreements between teams and companies — and why changing one can affect products far beyond the system that owns it.