Hey friends! If you’re here, you might be like me—working at ReadMe, but also have no idea what your co-workers are talking about half the time. Welcome! This is a safe space.
I’ve put together this list of API terms and explanations so you and I can get a better idea of what our friends are talking about and how APIs work. None of those in the weeds, mumbo jumbo explanations will be found here—only definitions that you and I dummies can understand. Don’t worry, I’ve asked our (actually qualified) co-workers for help!
Application Programming Interface (API)
Here we go! First of all, don’t try to understand what API actually stands for. It doesn’t really matter to us and just makes things confusing. Let’s talk about food instead.
When you go to a fancy restaurant, you’re given the beautiful ambience—everything is curated to look good together, work well, and suit your needs. This is like the user interface (UI) on the web that you’re used to using. For example, in Twitter anyone can easily tweet, retweet, like, search, etc. because the website is well-designed with nice buttons, colors, and text make your experience a breeze. You already know what happens when you click a button, just like how you know to pick up the menu and order something from the waiter. Within the restaurant (UI) environment, things are self-explanatory for customers (users).
Now imagine that on the side of the restaurant is a drive thru. Here, drivers can get multiple packaged orders, or even massive amounts of food for catered events. When you’re getting orders from the drive thru, you don’t expect the pleasant experience of sitting down, having tables prepared for you, and water cups set out in advance. You have to know exactly what you want, then the restaurant gives you the barebones package, and you take this package and provide your own setting.
This is similar to how developers can use Twitter’s API. For example, they can search tweets published in the past week with the term “nasa,” and get back every single detail about each tweet, from when it was posted, to the background color of the user’s profile.
You can use APIs to perform specific functions (like searching tweets), but what makes APIs really cool is that they’re also like Lego. You can use multiple APIs together, or build them into apps or websites.
The format of the API’s response makes it easy for another app to interpret, meaning someone can use the above Twitter data to create various charts or visualizations, or even use it to create a bot that automatically replies to all of these tweets! (This is how people create annoying Twitter bots.) The sequence creator is writing their own software to weave the pieces together in a pipeline that’s a lot simpler than if they tried to do each piece by hand. Kinda like how making a spaceship using Lego, it’s a lot easier than starting with nothing.
Note that APIs can do a TON of cool (and boring) stuff and understanding some of what they do doesn’t tell you what all of them do. And that’s okay!
(Thank you Kanad for the restaurant vs. drive thru explanation, and Jon U. for the Lego metaphor!)
API Terms in the Wild
API documentation
Ahh, the thing I learned about before I even knew what an API was. The documentation, or docs for short, explain how to use an API. Even engineers don’t automatically know how to use APIs, so they use the docs to learn how to use each one. Docs used to be static and boring how-to guides, including every possible use case and error code in a literal textbook. Nowadays, services like ReadMe let API creators make dynamic docs that let developers see how APIs should be used and test them out right there.
Documentation can go beyond use cases and guides though! At ReadMe, we believe that documentation also includes things like support forums, tutorials, and even error messages. More on that philosophy in a blog post by ReadMe CEO Greg, here.
Methods (POST, GET, PUT/PATCH, DELETE)
When you use an API, you use these verbs to make it do what you want. Here’s a handy dandy table that Engineering Manager Dom made to show which method does what. This was part of his HTTP API Faux Pas article for our blog! (Twitter thread)(blog post)
| Action | Verb |
|---|---|
| Create | POST |
| Read | GET |
| Update | PUT/PATCH |
| Delete | DELETE |
OpenAPI Specification (OAS), formerly Swagger file
The OAS is a file with all the information about an API. Because the format is standardized, the OAS can be used to automate things like creating documentation. API owners can upload their OAS into ReadMe and our program automatically creates interactive docs using that info! It works because it’s all standardized.
REST and HTTP APIs
These are standards for building web APIs that make using and creating them easier for developers. Someone somewhere decided that APIs should look a certain way, and those became REST APIs. The inventor basically tamed the wild west of APIs, and there’s a good story about that here.
Software development kit (SDK)
SDKs are like the sugar on top of an API. They essentially make the API easier for developers to use by hiding all the complicated stuff. Instead of needing to write 10 lines of code and getting confused, SDKs allow you to write one line of code that’s it’s easier to understand so it’s more powerful to use. This is like adding a delivery app to the restaurant so all you have to do is tap a button, not even drive to the restaurant.
Status codes (404 not found, etc.)
APIs have a set way they’re supposed to be used, and each time you put in a request, you get back a status code. They go from 200—a great request, you did everything right—to 500 plus, where things are really wrong (probably it’s the API that’s messed up). Each number has a specific meaning, letting developers know what they did right, or wrong so they can fix it. If you’re interested in which code means what, Greg wrote a ballad including error codes as if an API is a metaphor for love. You can find “410 Gone Away” here.
Try APIs Yourself!
From my background in writing and editing, I like to tell folks that the best way to learn to write is to read more. The same seems to be true with APIs! If you still don’t really get it, it’s a great idea to play around with an API yourself. Don’t look away. It’s really easy, I promise!
Our coworker Kanad made a Twitter clone called Hoot, and if you play around in the API explorer, you can see how your actions in the API correspond to actions in the UI.
Go here to find the UI 👉 https://hoot.glitch.me/home.
And, go here to find the API explorer and documentation 👉
https://hoot.readme.io/reference
Try posting a Hoot using the API. Under “Create a hoot,” type what you want to post in the “post” box. You’ll see that the code above changes to include the text that you input! Then click “Try It” at the top. Refresh the Hoot UI and see that your Hoot was published using the API!
I found that doing this really gave me a feel for what an API does (it’s not that crazy!) and how all the above terms come together in a tangible way.
APIs are pretty cool because they make it easy for developers to build new stuff without reinventing the wheel every time, which democratizes useful tools and data. I hope you can use this article to go out there and crush your convos about APIs, or learn more about them now that you have an idea of what they are! If you have any questions, feel free to ask any engineer. They’re all super friendly! Kanad and Jon U. are especially good at explaining APIs and willing to help.