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.
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: