SDK and API are 2 terms banded around a lot when developers think about accessing services or other functionality. But what are they, and what are the differences between them? This post will teach you everything you need to know and how SDKs can benefit your software development process!
Key Differences: SDK vs API
API (Application Programming Interface) is a set of rules that allow different software applications or services to communicate with each other. It defines how they can exchange data and perform functions. APIs are often used for integrating third-party services or accessing data from a platform, and they are language-agnostic.
SDK (Software Development Kit) is a package of tools, code libraries, and resources designed to simplify software development for a specific platform, framework, or device. SDKs are platform-specific and provide pre-built functions to help developers build applications tailored to that platform. They are typically language-specific and make it easier to access and use the underlying APIs of the platform they are designed for.
As we compare SDK vs API, here are some key differences:
| API | SDK |
|---|---|
| Pass data as JSON | Pass data as strongly typed objects |
| Call endpoints defined using strings | Call methods or function |
| No compiler or linter checking | Compiler and linter checking |
| No automatic retries | Automatic retries can be defined in the SDK |
| You have to read the docs to discover services or learn what data to pass or receive | Intellisense and documentation |
| Can be called from any programming language, as well as tools like Postman or low/no-code tools | Can only be called from compatible languages |
What is an Application Programming Interface (API)?
An API, or application programming interface is an interface to a system that application programmers can write code against. This reads like I'm just juggling the words around, so let's break down this statement.
There are many systems and services out there that you might want to integrate into your application. For example, you might want to use Stripe as a payment provider. As you program your application, you need to talk to these services, and these services define an interface you can use to talk to them - this interface lists all the things you can do with the service, and how to do them, such as what data you need to send or what you will get back from each call.
Application Programming Interfaces in the modern world
In the modern software development world we think of APIs as a way of making calls to a service over networks or the internet using standard protocols. Many services have a REST API - a set of web addresses, or URLs, you can call to do things. For example, a payment provider API will have endpoints you can call to create a payment or authorize a credit card. These endpoints will be called using HTTP - the same technology you use when browsing the internet, and can take or return data either in the URL, or attached to the call in what is called the body. These are called using verbs - well defined named actions, such as GET to get data, or POST to create data.
Calling APIs
Calling an API endpoint is referred to as making a request. The data that is returned is referred to as a response.
APIs can be called from any programming language, or from tools like Postman.
There are many protocols APIs can use, including REST, gRPC, GraphQL and SOAP. REST is the most common, and the one I'll be referencing in this article.
What is a Software Development Kit (SDK)?
A software development kit is a code library that implements some kind of functionality that you might want to use in your application.
What can SDKs be used for?
SDKs can implement a huge range of functionality via different software components - they can include visual components for desktop or mobile apps, they can interact with sensors for embedded apps, or provide frameworks to speed up application development.
SDKs for your APIs
Another use case for SDKs is to provide a wrapper around an API to make it easier to call from your application. These SDKs make APIs easier to use by converting the calls you would make into methods, and wrap the data you send and receive in objects.
These SDKs can also manage things like authentication or retries for you. For example, if the call fails because the service is busy, the SDK can automatically retry after a defined delay.
For the rest of this article, when I refer to SDKs I'll be talking about SDKs that wrap APIs.
How Do APIs Work?
APIs work by exposing a set of endpoints that you can call to do things.
API Endpoints
These endpoints are called using verbs that roughly align to CRUD (create, read, update, delete) operations.
For example, you might have a user endpoint that handles the following verbs:
| Verb | Description |
|---|---|
| GET | Read a user |
| POST | Create a user |
| PUT | Update a user |
| DELETE | Delete a user |
API Data
Data is typically sent and returned as JSON - JavaScript object notation. For example, a user might be returned as:
{
"id": 42,
"firstname": "Jim",
"lastname": "Bennett",
"email": "jimbobbеnnе[email protected]"
}
How Do SDKs Work?
Software Development Kits work by wrapping the API calls in code that is easier for developers to use.
Creating a user with an API
For example, if I wanted to create a user using an API, then my code would need to do the following:
- Create an HTTP client - this would be code from a library that can make HTTP calls.
- Create a JSON object to represent my user.
- If my API requires authentication, I would need to get an access token and add it to the request.
- Send the JSON object to the API endpoint using the HTTP client.
- Get a response and see if it was successful or not.
- If it was successful, parse the response body from JSON to get the user Id.
This is a number of steps, and each one is error prone as there is no compiler or linter to help you. For example, if you sent the first name in a field in the JSON object called "first-name" and the API expected it to be "firstname" then the API call would fail at run time. If you forgot to add the access token, the API call would fail at run time. If you forgot to check the response, your code would continue to run and would fail at some point later on.
Creating a user with an SDK
An SDK on the other hand would implement most of this for you. It would have a class or other strongly typed definition for the user object, and would handle things like authentication and error checking for you. To use an SDK you would:
- Create an instance of the SDK class.
- Set the authentication token once on the SDK so it can be used for all subsequent calls.
- Create an instance of the user object, and set the properties.
- Call the SDK method to create the user, passing in the user object.
- If this fails, an exception would be thrown, otherwise the user Id would be returned.
Benefits of Application Programming Interfaces
APIs are the perfect way to expose a service to your internal infrastructure or the world via the internet. For SaaS (Software-as-a-Service) companies like Auth0 and Stripe, their APIs provide the services that their customers use to integrate with their applications. Internally organizations can build microservices or other internal services that different teams can use to build applications. For example, a company might have a user service that manages users, and a product service that manages products. These services would expose APIs that other teams can use to build applications.
By using a standard protocol such as REST you are providing the most widely used interface - development tools like programming language and many low/no-code technologies can call REST APIs. This means that your service can be used by any application, regardless of the technology it is written in.
Pretty much. every service should have an API if it needs to be called from an application.
Benefits of Software Development Kits
SDKs on the other hand are software components that provide wrappers over APIs. They make it easier to call APIs without making mistakes by providing things like type safety and error handling. If you use the wrong name for a field on an object, your compiler or linter will tell you (probably as soon as you type it with a red squiggly in your IDE). If you forget to add an access token, the SDK will throw an exception, but once set it can be used for all calls, and not need to be set every time. If the API call fails, the SDK can retry for you.
The benefit of an SDK is this hand-holding - it's a wrapper around the API that makes your life easier. An SDK takes nothing away from your API, developers can still call it directly if they are so inclined, but the SDK makes it substantially easier to use.
How and When to Choose Between SDKs or APIs?
As a provider of a service, there is no choice as such. You have to provide an API so software developers can call you service. Should you provide an SDK as well as part of your development process? Well, yes - it improves the experience for your users, and makes it easier for them to use your service. If you don't provide an SDK, then your users will have to write their own, and that's a lot of work for them. Keep your customers and users happy, right?
Conclusion
In this post we've looked at the differences between SDKs and APIs, and when you might use one over the other. We've seen that APIs are the interface to a service, and SDKs are wrappers around APIs that make them easier to use. We've also seen that APIs are the best way to expose a service to the world, and SDKs are the best way to make it easier to use an API.
Can I automate SDK generation?
The obvious question now is how do I create an SDK for my API. You could write one yourself, but why do that when liblab can automate SDK generation for you as part of your software development process? Check out liblab.com for more information and to sign up!
