To watch the youtube video where I explain this topic, click here.
So We Want To Make An API...
In the previous blog post, we went over what an API is and and the steps required to make one. As part of a learning process, we're going to be making our very own API, while going through all of the steps involved in making an API.
In this article, we'll be planning what our API does, and creating the Swagger document so that any of our API users know how they can use our API. What Our API Does
Let's pretend that we run a website that sells fruits. We have a certain number of fruits in our warehouse. Sometimes we get more fruits because shipments come in, and sometimes we sell fruits. We have a website for our customers to buy fruits, and a few in-house applications for our staff to use so that they can report sales and shipments. We'll have a database that stores the number of fruits we have, and we'll create an API to facilitate all of these different software interacting with the database.
So let's define a few things that we want this particular API to do:
Our API Specifications: Careful Planning
Okay, first of all, assume that we have some form of data persistence. This is most likely a database, with a table with columns for the fruit name and quantity, but could also be in some other form.
Next, our list of APIs will be specified by this table.
It's pretty bare for now, but we're going to be specific about all the details when we create the swagger document.
What Is Swagger?
Swagger is sort of like a markup language. You write the specifications of your API in their particular format (in a yaml file (or json, but the json version isn't as good)), and then you can view your API specification in a very pretty formation.
Anyone who needs to use your API can easily see the available paths, what they need to do to use your API, since examples and documentation is there in a very easily readable format.
(It also makes it easy to code the API later since everything is clearly defined.) How To Use Swagger
I'm going to be 100% honest here...I never actually remember the exact details of yaml for making a Swagger document. Usually, I just go to the template page for swagger, and overwrite the petstore example with my own API needs.
After a while, you'll remember the syntax and how everything is done, but for now, just look at the syntax of the petstore example and change the methods and names and parameter types as necessary for the API you're making. Again, go to this webpage and change the things you need: editor.swagger.io/ Our API, Defined In Swagger
This is the swagger code for our project. I looked at the plans that we had before, and made the swagger document for our API's needs.
Does it seem complicated? It's not. Watch the video and I'll go over what everything means.
Copy and paste the code into the swagger editor to see it in it's full glory. What's Next?
Well, so far we're learned about APIs, we planned one out, and even made the swagger document for it. Next up is...coding!
I'm going to be coding this in both Java and NodeJS, so make sure to go to the appropriate article for the language you prefer. To see this API coded in Java, click here. To see this API coded in NodeJS, click here.
Here's the youtube video where I go over the above code:
Like this content and want more? Feel free to look around and find another blog post that interests you. You can also contact me through one of the various social media channels.
Twitter: @srcmake Discord: srcmake#3644 Youtube: srcmake Twitch: www.twitch.tv/srcmake Github: srcmake
To see the youtube video where I explain the topic, please click here.
What Are APIs?
An API (Application Programming Interface) is basically a function over the internet, made over HTTP (the protocol that normal web requests use). It allows for certain functionality to happen, where the function exists somewhere on the internet and can be called from anywhere as long it's in the proper format has has correct authentication.
Common examples of API usage is for filling in content any time it's necessary in a website or app, or providing your API users with information from your database or some function to make it easy for them. For example, many times when websites load content (for example, item listings on Amazon), the pages aren't hard coded in HTML to load the details of specific items. Instead, the items exist as resources in a database, and an API is used to speak to that database to fill in HTML of the loaded web page based on a number of factors for the user. Another example is Google providing people access to their Google Maps API so they can use it for their apps or websites. APIs are very important and get used for basically any website or app that need some special work done (including speaking to a database or doing a special task). Consuming an API
An API can be called by simply using a URL, much like you'd use in your web browser.
https://www.google.com/maps/search/?api=1¶meters
If an API exists on the internet, there are three parts to properly
The URL path, parameters, and request body can all be customized to accept certain information for the request that you wish to make. (For example, for Google Maps API, we may choose to ask the API to give us an address if we give it latitude and longitude coordinates.) The implementation of the API is up to the developer. To see best practices, see this stack overflow question.
HTTP Methods (GET, POST, PUT, DELETE)
These methods get defined when you create your API.
Again, they're not actually part of some code or some magical rule that governs API servers...they're just convention. You could still make a deletion on a GET request, but that'd be considered poor practice. It's still possible. What an API Returns
There are two things that an API returns after making a request. The first is a response code. There are a bunch of response codes for different situations, and this website does a good job of going over them.
The most important response codes are:
The other thing an API returns is the content that was requested, called the response body. This usually comes in json format, but unpopularly, it may also come in XML format.
Making an API
An API is created writing some functionality in a programming language (typically Java and NodeJS are most popular), and putting that code onto a server that sits there waiting for requests. Pretty simple, right?
There are a few things that you should do if you want to create an API:
Let's Create Our Own API
This blog post was the introduction to a series on APIs! We're going to, from start to finish, create our own APIs using Java and NodeJS, following all the steps along the way.
The next step is to plan an API project and create the Swagger documentation. Click here to see the next article in this series, where we do that.
For the youtube video on the Introduction to APIs, watch it here:
Like this content and want more? Feel free to look around and find another blog post that interests you. You can also contact me through one of the various social media channels.
Twitter: @srcmake Discord: srcmake#3644 Youtube: srcmake Twitch: www.twitch.tv/srcmake Github: srcmake
To see the youtube video where I explain this complicated topic in simple words, click here.
What is Object Oriented Programming?
"Object oriented programming" is a style of programming where things are modeled as objects that have certain features and attributes that describe them, and actions that they can perform. For example, animals have names and a certain amount of legs, and they're also able to make sounds. In our code, we would create an Animal class that has variables and methods to model this behavior.
However, the trick that makes object oriented programming work well is by having hierarchies of classes to save on lines of code, while also remember to include all the features and methods that are necessary to describe the object. For example, if we wanted to make classes for Dogs, Cats, Squirrels, Horses, Zebras, Pandas, and Centipedes...they're all animals and have similar characteristics that we'd use to describe them, but it would be inconvenient to have to write the same lines of code for including those similar features in each individual class. Instead, we can create a base Animal class with the characteristics that all animals have, and we can create derived classes for each individual animal that will inherit from the base class, so that the derived classes also have the features and methods that the base class has. A Brief Warmup - (Base) Class Example
If you don't already know what classes are or how they work in C++, then look at the tutorial where we go over classes, templates, and custom data structures, as it explains how classes work very well.
For now, we start with a simple base class, and test it out.
As you can see, we have a fish class with two attributes, name and hasScales, and there's one public method available named Swim. We declare the name and hasScales variables as protected, meaning they're private, but derived classes can access them (as we'll see in the next section).
A Derived Class: It Inherits From The Base Class
So Fish is our base class, but there are many kinds of fish: goldfish, salmon, tuna, sharks, whales, and even eels! A lot of aquatic animals fall under the category of "fish".
We're going to create a class called Tuna that inherits from the Fish class.
You can see the syntax for inheritance, just use a semicolon and the base classes name. The public keyword allows the derived class to use public methods from the base class. (Take away the public keyword in line 25, and the "tuna.Swim()" on line 65 will throw an error.
The Virtual Keyword
So far, our derived class was really simple. But what happens if we want to override one of the methods in the base class? For example, our Fish class says that fish swim by "using fins to paddle forward", but Eels don't have fins...they swim by wiggling their body. How can we compensate for this?
The answer is the virtual keyword. The virtual keyword allows a derived class to override the base class's method definition with its own. In our case, we're adding the virtual keyword to line 13 in our base Fish class for the Swim method, and we'll override that method in our Eel derived class. Here's the code:
You can see that the Eel object named eel will use the Swim method with it's own definition ("wiggles body") when used normally. However, that would have happened even if the virtual keyword wasn't there.
The reason to use the virtual keyword is so that if you pass an object to a function, the function can accept the base class as the parameter, but use the derived class's overridden definition. If this doesn't make sense, watch the video where I explain it. Abstract Classes: Pure Virtual Functions
The final thing we need to know about is the concept of abstract classes. An abstract class is one with an incomplete method definition. For example, we might have all Fish eat, but different fish eat different things, and it doesn't make sense to create a default definition for an Eat method and overriding it: it makes better sense to let each individual fish derived class define an Eat method themselves.
So we'll create an Eat method in the Fish class, but we use a pure virtual function and we don't write an Eat definition. Basically, this means that all derived classes MUST define the Eat method themselves, or the compiler will throw an error.
As you can see, a "pure" virtual function just has an "= 0" at the end of it's prototype in the class definition. It means that the GoldFish and Shark derived classes HAVE to have a definition for the "Eat" method.
Conclusion
With this knowledge (on top of using classes in the previous article), you're an expert at object oriented programming! Congrats.
When modelling objects and larger projects, always keep in mind hierarchies of descriptions so that you can write as little code as possible. It seems pointless for small projects, but for very very large projects, planning the architecture, classes, and objects is more important than the coding itself.
To see the youtube video where I explain this complicated topic in simple words, watch this video:
Like this content and want more? Feel free to look around and find another blog post that interests you. You can also contact me through one of the various social media channels.
Twitter: @srcmake Discord: srcmake#3644 Youtube: srcmake Twitch: www.twitch.tv/srcmake Github: srcmake |
AuthorHi, I'm srcmake. I play video games and develop software. Pro-tip: Click the "DIRECTORY" button in the menu to find a list of blog posts.
License: All code and instructions are provided under the MIT License.
|