Suppose you are building a bookstore app. You might use a JSON library to read book data, call the bookstore's API to retrieve that data, and install a bookstore SDK to simplify those calls. All three can be part of the same integration.

These terms describe different things, but they overlap. Understanding the distinction helps you read documentation, choose dependencies, and identify which part of an integration needs attention when something fails.

This chapter explains each term and follows how they work together.

An API, or Application Programming Interface, defines how software can interact with a component. It describes the available operations, inputs, outputs, and behavior. An API can be the functions a local library exposes or the operations a remote service exposes.

A library is reusable code that an application can use to perform a task. It might parse JSON, resize an image, or communicate with a service. The library's API is the interface through which your code uses that implementation.

An SDK, or Software Development Kit, is a collection of resources for developing software for a particular service, product, or platform. It may include libraries, development tools, documentation, and examples. Its contents depend on what developers need to build for that environment.

The distinction becomes clearer when each term answers a different question:

These categories are not mutually exclusive. A library exposes an API. An SDK can contain that library. When a provider says “use our SDK,” it may mean installing a package whose main component is a client library.

Python's standard library, the collection of modules that ships with Python, includes the json module. Its loads function accepts JSON text and converts it into Python values. For example, a JSON object becomes a dictionary, a structure that maps keys to values.

The following example reads a small book record already present in memory:

It prints Designing Reliable Services. There is no network request here. The string is already available, and the library performs the conversion locally.

The function name, accepted arguments, returned values, and documented errors belong to the library's API. The code that recognizes characters and constructs Python values is its implementation. Python documents JSONDecodeError for invalid JSON input, so callers can distinguish malformed data from successful parsing.

The diagram separates the interface your code calls from the implementation that does the work:

The API consists of the library's operations that your code can call. It is not a separate server or extra program. This is why “library versus API” is not usually a choice between alternatives: using a library means using some part of its API.

A library does not necessarily perform all its work locally. An HTTP client library exposes local functions whose implementations send network requests. The word library describes how developers package reusable code. It does not promise that calls are fast, work offline, or have no effects outside the program.

A service SDK commonly provides a client library, reusable code that helps an application communicate with a remote service. That library can translate language function calls into network requests and translate responses into values or objects that the application can use.

Depending on the SDK, it may also help attach credentials, validate some inputs, handle timeouts, or retrieve results that span multiple responses. These capabilities vary. The label “SDK” alone does not guarantee any particular feature or behavior.

For a concrete example, the AWS SDK for JavaScript provides a JavaScript API for using AWS services from supported environments such as Node.js and browsers. It gives developers a language interface to those services.

SDKs also exist for building applications on a platform. The Android SDK includes packages for build tools, platform tools, and an emulator. An emulator lets developers run an Android environment for testing without requiring a physical device for every task. This SDK supports application development beyond making remote API calls.

The following diagram shows resources a fictional bookstore SDK could offer:

An SDK can package these resources in different ways. The documentation might live on a website while the library arrives through a package manager, a tool for installing and updating software packages. A platform SDK might add build and debugging tools that this service SDK does not need.

The boundary between “client library” and “service SDK” is therefore loose in everyday usage. Inspect what the provider actually supplies instead of inferring its contents from the name.

Assume the fictional bookstore exposes public book details at https://api.bookstore.example/books/book_1042. Retrieving this information does not require a login.

A client can use an HTTP library to send the request itself. The following HTTP/1.1 exchange illustrates the messages the client and service exchange over HTTPS:

The service returns a successful response containing the book's identifier and title:

The response body is the single line above, without a trailing newline. 200 OK indicates success, and Content-Type identifies the body as JSON. These are HTTP meanings, while the path and book fields belong to this fictional service's contract.

With this approach, application code chooses the URL, checks the response, and interprets the returned data. “Calling the API directly” usually means managing the service interaction through a general HTTP library, not writing networking code from scratch.

A bookstore SDK could expose the same operation as a language method. The following Python-style code illustrates a hypothetical SDK interface; BookstoreClient is an invented example, not an installable package:

In this hypothetical SDK, get sends the request, checks the response, and converts a successful result into a book object with a title attribute. The method call is shorter because the library owns those steps.

There are now two interfaces involved: the local API the client library exposes and the remote API the service exposes. This sequence shows the distinction:

The SDK method runs in the client environment, but completing this operation depends on the network and the service. The SDK does not move the bookstore's catalog into the application. It provides code that communicates with the catalog service.

Nor does every SDK method correspond to exactly one request. A helper may make several requests, and a local utility may make none. The SDK's documentation must explain the behavior callers need to account for.

When an SDK call fails, the source of the failure may be local or remote.

An invalid argument could cause the library to reject the call before sending anything. A connection failure could prevent the service from receiving the request. The service could receive it and return an error because the caller lacks permission. The SDK could turn that response into an exception in the programming language. An exception interrupts normal execution so application code can handle the error.

Those outcomes require different fixes. Correcting local arguments will not grant access to a private order. Updating the SDK will not repair a service outage. Investigating the library's error information and the underlying request helps identify which component is responsible.

An SDK can perform helpful checks, but the server still needs to validate inputs and enforce permissions. Another client can call the remote API without that SDK and bypass its local checks.

Updates have a similar distinction. An SDK version identifies a release of the client software. A service API version, where the provider exposes one, identifies a supported remote contract. Their numbering and release schedules need not match.

A new SDK release might fix response parsing without changing the remote API. Conversely, a service might add an operation that an older SDK has no method for. Whether an SDK selects or supports a particular API version depends on the provider's documented behavior.

This gives an integration two sets of dependencies to understand: the client code it installs and the remote behavior it relies on.

For a remote service, the practical choice is often whether to use its SDK or build the integration with a general HTTP library. Both approaches still use APIs and reusable code.

An SDK can reduce repeated work when it supports the operations, language, and runtime your application needs. A runtime is the environment that executes your program, such as Python or Node.js. Language objects, documented exceptions, and service-specific helpers can make an integration easier to maintain.

The trade-off is adopting the SDK's dependencies, release schedule, and behavior. Review how it handles timeouts and retries, whether it exposes enough error information, and whether it supports the service features you need. Convenience is useful when its behavior is understandable.

Managing HTTP calls yourself can fit a small integration or an environment without a suitable SDK. It also gives you direct control over requests. Your team then owns the code that constructs those requests, interprets responses, and handles failure. A short successful request does not represent the full maintenance cost.

For local tasks, such as parsing a JSON string or resizing an image, a suitable library may do the work without a remote service. For platform development, an SDK may supply tools you need to build and test the application. Start with the capability and environment you need, then evaluate what each package actually provides.

An API defines an interface. A library provides reusable code through an interface. An SDK supplies resources for developing with a particular service or platform, often including one or more libraries.

Using a service SDK typically means calling a local library API that communicates with a remote API. Understanding both interfaces helps you choose an integration approach, investigate failures, and manage changes to client code and service behavior separately.