APIs and SDKs and Microservices — what’s the difference?

APIs, SDKs, and Microservices are a way for a program to interface with and control the resources provided by another piece of software, whether that other software is a web service, an end-user app, an OS service or daemon, or a kernel device driver.

So… what are the differences between an SDK and an API and a microservice?

The TL:DR answer is that all modern SDKs are or contain APIs but not all APIs are SDKs. Microservices contain very small APIs offering discrete endpoint access.

The long form is as follows:

A Software Development Kit is the “box” that contains (or references) all the “tools” (APIs, documentation, samples, etc. that’s needed to create an application. An SDK could be nothing but an API (files to help interface with another app), but usually includes other code to help with debugging and other pieces for your IDE. In addition, Typically one SDK covers an entire platform or product. As examples, there’s one MacOS X SDK and one iOS SDK, and each of those contain API’s for many different areas of functionality. Documentation for a SDK usually is a team effort, and will contain many separate parts, often delivered in different modes.

An Application Programming Interface is a specification for a set of related methods that allow one program or service connect to a different program or service. For example, being able to link an excel spreadsheet to an Oracle database. Not all API’s are fully documented, and while examples can be part of the documentation for an API, generally the minimal documentation is functions, calls, data types, sizes/limits, and classes. More extensive (and useful) documentation includes supported protocols, supported file formats, error messaging, and so on. Sometimes there is a graphic illustrating the data flow or the workflow. A lot depends on how much handholding is expected. Also, whether a technical writer is involved to ask the tough questions of “what happens next?” and “what happens if XYZ occurs?”.  A lot of time, developers don’t think about such things unless they are forced to.

Be aware that these days the term “API” is often used (incorrectly) as a synonym for “library”. Part of a software library is the API that allows code to use the library, but the library itself isn’t an API.

“A microservice is a software development technique—a variant of the service-oriented architecture (SOA) architectural style that structures an application as a collection of loosely coupled services. In a microservices architecture, services are fine-grained and the protocols are lightweight.” [Wikipedia]

So, a microservice essentially breaks out each set of functions as a separate-but-related logical group, each of which will have its own API. These APIs may have much in common, but by making them separates, it is then possible to update/fix/change one service without affecting the others. Documentation for a microservice is usually similar to that of APIs, but may include material on how the APIs interact.