2' What's an API anyway?

April and Emily break down what APIs are, best practices, and how they are relevant to society today.

Transcript

Emily: 0:06 
Hey, everyone, you’re listening to Tech & Savvy. I’m Emily.

April: 0:10 
And I’m April.

Emily: 0:12
 And today we’re going to be talking about APIs or application programming interfaces. So April has a lot of experiences with API. So she’s going to be leading the discussion. So April, do you want to tell us a little bit about your background with APIs? Before we get into really talking about what APIs are, best practices, things like that?

April: 0:33 
Yeah, sure. I’ve created REST APIs that integrate with legacy services and enterprises, which were mostly built using SOAP web services and a SOAP architecture. And then I also have experience building APIs that deal a lot with resource management. So these APIs would interact with databases such as MySQL, Cassandra, GemFire, PCC, which is also known as Pivotal Cloud cache. And that’s really the brunt of my experience. What about you, Emily? Do you have any experience with APIs?

Emily: 1:11
 I have a little experience with APIs specifically implementing cryptographic APIs in C#, .Net core, REST APIs in particular. And even though I have a little experience, I still feel like there’s so much I don’t know about API. So I’m excited to learn more. Yeah, so let’s get started. So, April, can you tell us a little bit more about what an API is? Give us some kind of intuition for someone who doesn’t know what APIs are.

April: 1:41 
Yeah, sure. API is an acronym for application programming interface. And what an API does is that it acts as a middleman between two services. And it defines the types of interactions that can occur between two applications. And what APIs do beyond that is that they make programming easier for a lot of developers because it abstracts out underlying information. So really, the guts, the core parts of a task, that really aren’t as necessary for what you’re trying to implement, and only gives you the necessary objects and functions, really, to get done what you need to get done. A great example of this, that I like to use, and that I’ve seen a lot is the restaurant example. So let’s say you go to your favorite restaurant, and a waiter comes by, and they give you a menu. And that menu has burgers, French fries, steaks, really anything you can think of. That waiter, who came by with the menu, that’s your API. And that menu is the set of interactions that you can have with the restaurant. So it’s telling you, you can order these menu items. And that’s what you know, and it gives you the list of ingredients. So you know what will come along with that menu item. You know what to expect from that API. So you decide that you want a burger. You say I want it medium one with lettuce, tomato, bacon, cheese, you know, basically, the best burger you can think of you ordered that burger. And you tell the waiter and they bring that order to the kitchen. That interaction is the API call. So now, your waiter said, “Okay. They want this burger. Let me go tell this other service, what needs to happen?” The kitchen goes to work. They make your burger exactly how you want it. Then eventually, your waiter comes back and you have your burger. So you didn’t know what was going on in the kitchen. You just know what you wanted. And it came back. And so what comes back to you is the API response.

Emily: 3:59 
Thanks. I love that analogy, April. So the waiter is the API. And the API call is telling the waiter what you want. And I think that’s also... When I was just talking about what my experience with API, my immediate thought was, “Oh! I have some experience implementing APIs, limited.” But then I realized just in doing this tutorial the other day for flutter, I was actually making API calls. So can you give a few examples of where they’re used? Either where somebody who’s in tech, maybe use an API or even examples of somebody not in tech, where they might have either seen or use an API in some way?

April: 4:46 
Yeah, sure. So one API that you can possibly think of is a popular one is the Google Maps API. Often even if you’re not on Google Maps, if you go on to, say a doctor’s office website, they probably have their address at the bottom. And sometimes you’ll see a get directions link. And that link is a lot of times connected to the Google Maps API. And so when you click that link, it takes their address through an API call, and also gets your location. And that’s how you’re able to get directions to the doctor’s office. Another instance where you might see where APIs are being used is if you go on Instagram, when you go on Instagram, the reason you’re able to see all of your friends’ recent posts is because of an API call that connects to Instagram. It takes your username and all the people you’re following, and it collects all their recent posts to display to you. When you decide you want to send your friend a DM on Instagram or Twitter, that’s also an API call. That’s how you guys are able to communicate with each other. So APIs are pretty much everywhere. And a lot of developers, most popular APIs that people see are usually web APIs. So that’s why you hear a lot of things regarding REST APIs or SOAP APIs, because those have a lot to do with web services and web applications. But also kind of like what you were saying, Emily, when you use libraries as part of development, those are also APIs. Because the point of API is, is that it’s Application Programming Interface. It’s not specifically associated with the web. It’s just a specification for how you can interact between particular services.

Emily: 6:44 
Okay, yeah. Thanks for clarifying that. So a library is a type of API.

April: 6:48 
Yes, basically, a lot of software library does act as an API.

Emily: 6:53 
So the definition of API seems very broad.

April: 6:58 
Yes, it is very broad. Okay.

Emily: 7:01
 Yeah, that’s good to know. So can we break that down a little bit? Can you talk about the different types of APIs?

April: 7:08 
So there are definitely are a few different types of APIs. We’re will focus on web APIs, remote APIs and software libraries and frameworks for this particular podcast. So let’s go a little deeper into each. We’ll start with web APIs, which I would say are probably the most common / referred to APIs, when people are talking about APIs. And the way web APIs work is that they define interfaces that utilize exposed URLs, also known as endpoints with a specific request response relationship that’s typically represented by JSON or XML. And the two most popular types of web APIs are REST and SOAP. REST stands for representational state transfer. And when someone builds a web a REST API, it needs to it here to six guidelines. So the first one is a client server architecture which is essentially a separation of power. The user interface is completely separate from the data storage. The second one is statelessness. What statelessness means is that the data stored on the server, that data state is independent of the server. It’s stateless. Nothing really changes. And it’s up to the client side to communicate to the server that that resource needs to be updated. Then third one is cache ability. That has to do with whether or not you should continuously make the same API call again. But really, the only time you would want to cache something is if you know [that] it’s not something that that gets updated in real time. So then moving on, the next guideline is the concept of having a layered system. So still, we’re here in this client server architecture. So the part that you are interacting with as a user is entirely separate from where the data is. But now we’re getting into the part where we can start putting things in between those two layers. So if you wanted to have more security, you might add an authentication layer. Even though we’ve added an authentication layer that still doesn’t interfere with the results that you would get from the API. And then you could add proxy layers, just really kind of stacking in between that client and that server. That’s the concept of a layered system. And then the next part is that there is a uniform interface. So each endpoint and request and response just needs to have the same type of structure. And then the final guideline is actually optional. And it’s called code on demand. And that essentially deals with when a server is able to kind of give extended functionality to the client side. And so those are the six guidelines that you’d have to get here to for REST.

Emily: 10:41 
Okay. So that was a lot of information. Thank you, April for going through that. It’s a lot. I feel like REST is a lot when I first learned about it. I was like, “What?” I just thought REST mean, it was like “Lazy.” You know, it was just resting. 

April: 10:54 
Yeah. You know, you would think.

Emily: 10:55 
Not at all.

April: 10:58 
It sounds so simple. But there’s a lot that goes into it.

Emily: 11:05 
So to summarize what you were saying REST, or R-E-S-T is a type of web API. And REST stands for representational state transfer. And an API is considered a REST API, if it adheres to six guidelines, which are client server architecture, statelessness, cache ability, layer system, uniform interface, and possibly code on demand, which you just summarized. And so that’s REST.

April: 11:43
 Very brief, you could probably have a whole podcast on REST. But that’s a general overview on REST. And the second type of web API that we’ll talk about is SOAP. And SOAP is an older architecture. And it’s used in a lot of enterprise settings. So SOAP stands for simple object Access Protocol. And it’s a messaging protocol for exchanging information between web services. And the interesting thing about SOAP is that it’s very strict and that the entire request response relationship is structured using XML. And that is useful and that you kind of always know what to expect. And you always kind of know what format your data is going to come back in. It’s a little restrictive, because not everything can come back as XML. So it can create some frustration for developers, I would say. The standard SOAP message is made up of an envelope. And so an envelope is just saying, “Hey, this is a SOAP message.” And then within that envelope, there will be a header section that will have parameters, usually that needs to be sent to the server in order to communicate such as authentication tokens are optional parameters about what you want to get. And then the biggest part will be the body. And that will have the information on what queries are being sent to the server, and then also the properties associated with the response that you’re going to get back. The last part of a standard SOAP message is faults, which gives you information about the errors that occurred during that message processing. So if the developer didn’t send a correctly formatted zip code, then it would say, “Hey, request failed. Zip code format invalid.” Or something along those lines. And then, like I said, it’s often seen in very large enterprises when there’s a lot of communication happening within distributed systems.

Emily: 14:17 
Okay, so you kind of answered when you would use SOAP as opposed to REST. Do you have any recommendation if somebody wants to learn more, starting with SOAP or starting with REST? And depending on I guess, where you’re thinking of using it or how, what would you recommend?

April: 14:36 
so I would start with REST just because it's a more modern take on web APIs. It's what you'll see being used most often. However, if you're looking to you know become a developer at a very large corporation that has been around probably for more than 30 years, there's a high likelihood that they have some legacy systems that are using SOAP. So it's always great to have experience in implementing both. But if you're just getting started, I would start with REST. That's always a great starting point. 

Emily: 15:16 
Okay, and do you have a language of choice or suggestion that you think people should use, if they want to just get started implementing a REST API or SOAP API?

April: 15:28 
Oh, yeah, sure. I've used Java and Katlin. However, you can also do it using Node.js.

Emily: 15:37 
Alright. So that was a lot of information about web APIs. And we talked about REST APIs, which are more commonly used and definitely a great place to start if you're looking to start implementing or just learning about web APIs. And we also talked about SOAP, which as April pointed out is more commonly used in large enterprises. So after going through a lot of details about web APIs, April, can you tell us about some of the other types of APIs?

April: 16:10
 another type of APIs that I said we were going to talk about are remote access APIs. And those APIs deal with communicating between databases. And those APIs allow the manipulation of remote resources. So in these cases, you will have a server side application and then you will have the actual database where your data is being stored. So where your data is currently being stored, that's static data, it's not changing. However, you have this server side application that is using this remote access API in order to manipulate the data in the database, so it can be updated in the future. And so typical databases, you might see being used with these types or databases that are generally communicated with are MySQL databases, Cassandra, Mongo DB. Commonly, these remote access APIs deal with CRUD architecture. And CRUD stands for create, read, update and delete. So for create, that's when you're inserting a new resource into a database. When you're using the read functionality, you're retrieving that resource from the database. Update means you're modifying that resource, but you're not overriding the resource, you're just modifying it. So there was a resource that had your name and phone number, but you needed to update your phone number, it would just update your phone number. And then the last one is delete, which is pretty self-explanatory. It deletes the resource from the database. So with remote access, all you want to do is communicate with the database that has information that you want to access or update or put there. 

Emily: 18:17 
Okay, yeah, that makes sense. 

April: 18:19 
Yeah. And so an example of a remote access API is the Java database connectivity API, also known as JDBC, which deals with connecting to databases and executing those CRUD operations that I just talked about.

Emily: 18:36 
Okay. And when you're using like a web API, for example, you are, in a sense, still interacting with the database, but you're not directly accessing that, right? 

April: 18:48
 Right. So many of the so many types of APIs are being used together when you're using an application. Let's say you're on Instagram and you decide that you need to update the email associated with your Instagram. So you update your email. And then you click Save. There's an API called made to a back end service that says, "Hey, I need you to update this resource with Emily's new email address." And then that server probably will end up calling a remote access API that will manipulate that resource in the database to update your phone number. I mean, your email, but you know what I mean, either way, right? So that's remote access APIs a lot easier to understand than web APIs, I would say. Our last type of API that I'd want to talk about are software libraries and frameworks, software libraries and frameworks, these APIs act as specifications for a particular component. When you think about the library, that's the actual underlying implementation that the developer doesn't care about, I know that I can use a function in this library, and it's going to give me what I want. It's doing all the hard work for me. And within frameworks, there are typically several libraries with their own APIs. And, as opposed to just calling the functions, developers typically have to extend these frameworks in brand new classes. But still, you're getting a lot of stuff for basically nothing. Interesting example I would use when talking about libraries is, if you've used Python, which is a programming language before, it has a stats module, which will execute predefined statistic functions for you. If you had a list of numbers, and you wanted to get the standard deviation between that lists of numbers, you can just use that statistics module and call dot standard deviation and put in the numbers and it's almost magic and it does all the hard work for you and you get the standard deviation back. So that's an example of software libraries and frameworks and those types of APIs you see in there.

Emily: 21:29 
Okay, yeah, that makes a lot of sense. And as someone who's used and developed libraries, I don't usually consciously think of them as being types of API. So thank you for clarifying that. So we talked about a lot of different types of APIs, and April, are there a lot others, too, that we're not getting to? Or does that really summarize it?

April: 21:48 
I would say that summarizes the main ones as there are also other APIs that have to do with operating systems and allowing different types of languages to be decompiled and compiled and other languages. They're not as prominent, as I would say, these three are in development, not to say they're not used. But I would say, if you're really trying to get into APIs or you're thinking about APIs, these are like the main three that you should probably know about.

Emily: 22:23
 We talked about web APIs. We talked about remote access APIs. And then finally, we talked about libraries and frameworks, which many people may or may not be familiar with and how those are also types of APIs. So are there any other characteristics that go into defining APIs, for instance, who can access what API?

April: 22:47 
Actually, there are generally three types of ways that APIs can be released. Those three categories are private, partner and public. Let's start with private. Private means its internal company use only, you can't use it, a company's business partner can't use it, and it’s purely for internal use. Then you have a partner release policy, which means that this API is being made available to specific business partners. So you have particular clients that need to use your API for their particular project. And so you make that API available to them. But it still allows for very strict quality control on your end, you have a lot of control over your API. The third one is public and public APIs mean they're available to everyone. Everyone can use the Google Maps API, everyone can use the PayPal API to have PayPal checkout. That means third parties who aren't your business partners can develop and create apps that utilize your API. This is great. And that when you open things up to more people, that leads to innovation and more revenue streams, more people who are using your API and paying you, the more money you get. But also you end up seeing new creative ways your APIs being used that you might not have thought that it could be used as before. 

Emily: 24:18 
Alright, so now that we talked about the different types of APIs, and also the different release policies for APIs, can you tell us some more about best practices if you're implementing an API?

April: 24:31 
 So to me, there are really three ingredients for if you want to have a really great API, an API that developers love, and those three ingredients would be good documentation, clean and reliable data, and sensible data structures. So first, let's start with good documentation. Have you ever built furniture with really horrible instructions? Like they don't even give you word instructions, they just show you pictures. 

Emily: 25:08 
Yes. And I usually have someone else build it for you. That's terrible. 

April: 25:14 
 Exactly. It's a horrible, it's a horrible experience. And it makes you not want to buy furniture from that particular brand or company. Again, because it was so frustrating. And that's the same thing with APIs. Your API can be as great as you want it to be. But if you have bad documentation on how I connect with your API, if you have bad documentation on why am I getting a particular error back from your API, or you don't really explain your property's that come back in your response, it becomes very frustrating for developers. Because then you're just fighting with trying to figure out how it's supposed to work. If you have an API, and you constantly need to be in meetings with clients, because they can't figure out how to connect to your API, you probably need to work on your documentation. Documentation will definitely make your API great and it can also break your API.

Emily: 26:27 
Good to know. I've been in that experience, too. Not just not with APIs necessarily. But just in general, good versus bad documentation makes such a difference.

April: 26:37 
It really does. And, you know.

Emily: 26:40 
Otherwise, Stack Overflow becomes your document.

April: 26:45 
It's so many developers... Many will say that, a lot developers will say, "They're not the biggest fans of documentation, because that's not the fun part."

Emily: 
26:54 But it's not the fun part.

April: 26:56 
Not the fun part, but it's a very necessary part. And even though, not many developers don't want to do documentation, when you have really great documentation, a lot of developers are like, "Oh, that's really great documentation. This is fantastic." So make sure API has really good documentation.

Emily: 27:14 
So April, as someone who's implemented APIs, would you recommend documenting as you go or waiting until the end, which is very tempting, and documenting everything at the end?

April: 27:27
I would definitely say you should document as you go. And actually, there are a lot of libraries that will actually create documentation for you if you run tests. So for example, I've used ASCII docs in the past which allow me to create particular tests for my APIs. But those tests also end up creating documentation for me. Another library that I've used is Swagger Docs, which, if you just use like particular annotations, it'll create a Swagger Docs file for you, that'll have your request and your response body, and then you can fill that in as you go. But I would definitely say, "Do it as you go." I know it's tempting to do it at the end, I've done documentation at the end, and I’m not going to pretend I am perfect. But I think we all know that we sometimes forget things. So it's better to just do things in the moment than trying to remember every single little detail as to why this is the way it is at the end.

Emily: 28:39 
 That’s good advice that I'll try to follow.

April: 28:42 
Yeah, you know, I should probably try to follow it too, right.

Emily: 28:45 
So you mentioned the next one as clean and reliable data.

April: 28:50 
Yes. 

Emily: 28:50 
Can you go into detail?

April: 28:51 
Oh, my gosh, let me tell you nothing. I know I said documentation will break your API. But let me tell you, nothing will make an API worse than bad data. If you have that data, don't even think about releasing your API, because it's going to be unnecessarily frustrating. And so one example I'll give this is that I had a friend, they went through a toll in their state and it was one of those tolls where you don't pay people, you just drive through and then they say you can pay the toll online. So they knew that they had this toll, and they went on their state's toll website, and they put in their license plate number, nothing came up. They didn't have anything about missing toll that needed to be paid. And they looked quite a few times, come to find out a week or two later, they got a letter from the state saying that they owed a toll and also the state was going to try to charge them an extra $10 because they had to send an invoice to them. And they went on the website again and still when they put in their license plate that told then it come up that came in the mail. And so that's an example of bad data. Why was my friend getting to different situations? They had something on paper that said they owed something. But when they went online, they couldn't find the toll. So bad data means there's a bad API experience. I don't care how fast your API is, I don't care how nice your documentation is, how clean everything is, if you have bad unreliable data, it's ruined, you'll need to work on that.

Emily: 30:37 
I definitely agree. Very frustrating.

April: 30:39 
It sounds harsh, but please, please, have your data together first.

Emily: 30:46 
Very good suggestions. So how clean and reliable data and then you mentioned sensible data structures?

April: 30:55 
Yeah. And this one is more so because when a lot of APIs are being built, sometimes all the business cases for a particular API or use cases aren't necessarily thought through when that API when it's being implemented when there's an exception for that API. And what will happen is, you might have a new client and they need something from that API. Now, that use case is a lot more complex. And the response/data structure that you decided to use doesn't fit with what they wanted. Now, of course, it's not necessarily a huge deal. And that you can create a V2 of your API that matches with what they want. But you don't want to continuously get into a situation where then you have to make a V3, V4, V5, because you keep having these clients come in with use cases that really don't work with your data structure. So really, this is just think of all your use cases beforehand, and then pit and then figure out a response structure that could be as agnostic as possible, and as reusable as possible between multiple clients. It'll make your life easier, it'll be easier for you to scale your API. So yeah, that's why it's just another part of what I think would make a good API.

Emily: 32:33 
Okay, so to summarize April's best practices, we have good documentation, because if things aren't documented, well, it's just a headache for everyone. And if you can try to document as you go, then clean and reliable data because you don't have good data. Why are you even doing this? What are you even doing? Make sure your data is good. And then finally sensible data structures, which is really about anticipating all the different possible use cases that somebody might want to use your API for and get that data and anticipating that and creating a good structure that will allow them to use it in every way that they can? 

April: 33:18 
Yes. 

Emily: 33:19 
April, do you have any other best practices, suggestions, tools you recommend? Anything else before we wrap it up?

April: 33:27 
Oh, no, I think that's about it. Unless, Do you have any other questions, Emily?

Emily: 33:33 
No, I think that's a very full view of APIs. I know, I still have a lot to learn about them. So that was really helpful.

April: 33:43 
Yeah, I know, APIs it's such a large subject and like Emily also said in the beginning, when we were starting to talk about it is very, very broad. So there's a lot that you can you know, there's lots of different niches you can get into and look into it. Try building your own APIs, try integrating with APIs. Just get your feet wet, you'll see that they really do make your life easier. 

Emily: 34:11 
Thank you, everyone, for listening. This was Tech and Savvy Episode Two, APIs with April. So thank you and our outro and intro song is gone by 414. All right, see you in the next episode, bye.