APIs and SDKs, What's the difference?

Published on 2021-08-03

What is an API? what is an SDK? and what is the difference between an API and an SDK? a lot of people get confused on this topic, especially because they are kind of related, so we wanted to make an article to just describe to you what each of these things is, how they are related to one another, and why they are both important.

What is an API?

From the classic computing definition, an API stands for application programming interface and it essentially deals with how software components can speak to one another. For instance, if I’m writing an application and I want to use a particular part of the Windows operating system, I don’t magically know how to do that, I need to go look at the windows documentation to understand which class I need to use, which function I need to call, what the input is of that API, what the output is and how all that stuff works.

Well, this is an API in the classic computing definition. Programmers interact with APIs all the time in order to do things using their programming language of choice and so this is where the contract of the API comes in. This is demonstrated through classes and functions like those mentioned above.

However, when most people tend to think about APIs, they tend to think of the second definition, which is in terms of cloud computing.

So what is an API from the cloud computing perspective?

Well, from the cloud computing perspective, an API is more concerned with data exchange from the client and server. So the client is the one that’s requesting the information and the server is the one that has access to that information. The server may not have that information stored locally, it may just know how and where to get it. That is the main role of the server in this relationship.

There are different specifications of how this process exists. How do you get information from a server that has this stuff over the internet? So there are a couple of different implementations of this, the most popular having been formed in the late 90s’, called SOAP. More common these days though is REST, which is pretty much everywhere. Any company that exposes an API is probably going to give you a restful endpoint where you can access their resources, but more recently there’s a real big take-off with GraphQL, which is an alternative way to access the same information. Now, one important point that has to be made here is that SOAP, REST, and GraphQL all contain and expose APIs to their clients in order to expose information. However, they just do it in a slightly different way, so this is where the different specifications are opinionated in how information should be requested and how that information will be returned back to the client.

Now let’s take a look at this from the REST and GraphQL perspective, because out in the wild this is probably what you’re going to find, these being the most relevant ones today.

So from the REST perspective, developers on the back-end define resources and this is what an endpoint for a resource may look like.


So you’re defining a user’s resource and you’re trying to find the user with ID number three and you can also have more specific resources that you’re interested in with regards to this particular user. In this specific example, we are interested in user ID number three and the comments that they have associated with them. So this is what a restful endpoint would look like using the very classic definition of what a REST API is. There’s also a variation on REST APIs, which is called RPC, which stands for ‘remote procedure call’ and it’s essentially a different variant of REST API, so you’re not working with resources in the classical sense where you have this kind of special syntax and the special notation. It’s more flexible and less cryptic in terms of the syntax, so you may have an RPC API that says like ,,get comments’’ and within the get comments API, it takes a user ID as an input and a whole bunch of different things to later return a certain output. These are two different variants using REST on how to perform the same thing, the one that we’ve exemplified above is the very opinionated classic definition of a REST API and the other one that we’ve just described is the RPC variant.

So in the classic REST API, there are four different verbs that you usually use, there’s ‘get’, ‘put’, ‘post’, and ‘delete’. So if you call the ,,/users/3/comments” API using this particular endpoint with a ‘get’ verb, this would just get you the information for this particular user, it would get you the user’s comments. If you call this same API with ‘put’ or ‘post’, then that means you’re attempting to create a new comment or update the content of a comment, and if you’re doing the same thing with a ‘delete’ verb, then that means you’re trying to delete all the comments, pretty straightforward.

Now, this has worked for a long time but part of the reason why we’re starting to move to a different solution such as GraphQL is because this model is very inflexible, it’s very strict. So if you imagine a world where you want to add a new use case to your application, maybe it’s a website and it’s communicating with a server that has access to a database and you want to add a new feature to your front-end application, if there’s no existing REST API that provides that data for you, a new one needs to be built. So you need to kind of interact with the back-end developer, the back-end developer needs to create a new API, it needs to connect to a database, they need to expose that API to the front end, and then the front end needs to read off that API in order to get its data. This is a very big problem in terms of speed of development, which is why the industry seems to be a fan of GraphQL, which greatly simplifies this problem. So GraphQL uses a slightly different model, again it’s all in the domain of exchanging information with the resource server but it just accomplishes it in a slightly different way. Graphql is more entity driven and flexible, so it doesn’t suffer the same problems that REST APIs face because GraphQL APIs just expose an entity and the types of operations that are allowed to be performed on that entity and puts a lot more power into the hands of the front-end application, meaning a lot more business logic can exist there. It’s really hands-off from the back-end developer perspective. This is great because it gives the front-end a lot more flexibility, allows you to develop features more quickly but it also has some security and scale concerns.

So GraphQLs don’t have this concept of resources like we saw earlier, they have a concept called ‘TYPES’. TYPES are a kind of one-to-one mapping of your entities, so in the ,,/users/3/comments,, example, we may create an entity called user and the user can have comments that are associated with them. That’s what a GraphQL entity would look like. From there we can define queries on these users and the queries essentially define how you can retrieve information and mutations define how you can create or update information. The great thing about GraphQL is that it provides a third concept called subscriptions. Graphql uses a subscription model where a user can subscribe to a particular entity or a particular thing that they are interested in and get live updates from the backend server as events change on the backend. So it’s a very powerful concept that is provided as part of QraphQL.

All in all, the definition that we’ve put forward for you in terms of cloud computing is probably what most people mean when they say APIs. It’s mostly with respect to how clients are getting information from a server, how that information is going to be requested by the server and given back to the client. That’s generally what you should think about when you hear the term API.

What is an SDK?

So what does SDK have to do with this? We talked about APIs, how information is exchanged from clients and servers and how it can be exchanged from different software components. So where does the term SDK come in here? Well, it turns out SDK it’s very closely related.

It stands for ‘software development kit’ which is essentially a grouping of tools to use for a different product or service.

For instance, if I want to use the Windows operating system, I would download the windows operating system SDK, and with that, it probably would contain an IDE, probably something like visual studio code or visual studio, it would contain probably a C++ or C# compiler, it would contain all sorts of documentation of all the different APIs that it exposes, what they all do, what the inputs are, what the outputs are, and how to basically do things with the windows operating system.

Conversely, the same thing applies if you’re using an API in the sense of a cloud definition. You’re not going to get an IDE in this case but you will get documentation that suggests how to use this API. You may also get helper classes and helper functions that make it easier to call different APIs over the internet.

An important thing to note here is this third point here is SDKs can contain utility classes to call an API.

Take a second to try and wrap your head around that. An SDK contains classes to call an API, an API does not contain anything regarding the SDK but the SDK contains things that help you to call an API.

Let’s take a look at a very concrete example here of me trying to call an AWS DynamoDB database.

So say I have this table that exists in AWS DynamoDB and I want to call it. How do I actually do that?

Well, the first thing I need to do is to download the [AWS SDK](https://aws.amazon.com/tools/. I need to go to the AWS website or use something like MPM or Maven, depending on your language of choice, to download that SDK, so I can actually call methods which in turn will call DynamoDB. So I download that SDK and I add that to my project. Once I have that SDK installed, I need to find the method and the class that exposes how I can get information from my table that exists in DynamoDB.

Here is what it looks like if you’re trying to use the get item API.

response = dynomodb_client.get_item(
        'artist': {'S': 'Arturus Ardvarkian'},
        'song': {'S': 'Carrot Eton'}

So in this code what are we looking at? We’re storing ‘response’ and we’re using the ‘dynamo’ to be client and we’re calling the ‘get_item’ function on this DynamoDB client. We’re specifying some input arguments, we’re saying this is our table name and we showcase the key and the value that we want to get. We’re trying to get an artist that is named Arturus and then we’re also trying to get the record where the song is, looking at the value attributed to ‘song’.

So this is an SDK, this is you’re using an SDK and when you use this SDK to call this function, you are in turn going to be making a REST API to the DynamoDB endpoint, where it will receive your request and return things back to you. So DynamoDB exposes multiple REST API endpoints for each of these different operations that you’re trying to do, maybe for ‘put’ item, maybe for ‘update’ item, maybe for ‘delete’ item, maybe for queries.

All these different things, it has different APIs that it exposes so that you can accomplish these operations.

In tandem, there’s also a function that is exposed in the AWS DynamoDB SDK, which allows you to easily call that REST endpoint that is living in DynamoDB. So you use the SDK to call a function, that function is going to perform a request on your endpoint that exists in DynamoDB and then it’s going to return a response back to the user. Probably the most confusing part it’s this relationship between SDKs and APIs, but this is kind of how it works in real life.

So moving on to the summary, just to go through the points really quick, APIs define how to access a resource, that resource can be locally, it could be using the Windows SDK to access a resource to create a dialog box or a pop-up window or something like that. Resources can also exist on the cloud, they can exist on a different server that has information somewhere on the internet where you can access it and retrieve information from, and then SDKs are a toolchain and they can contain tools including functions, classes, and so on to call APIs. That’s really where the distinction is.

We hope this article cleared up for you the difference between APIs and SDKs.