APIs are an important aspect of web development and a foundation of programming. As a web developer in training and Computer Science student at the Swinburne University of Technology, having a strong foundation in these disciplines is essential. But beyond setting a specification and clear objectives, creating a good API is as much an art as it is a science.
In my web development experience, it’s daunting but necessary to learn new things, especially as a student. The perspective I get from my student peers is that the world of software especially is nothing but constant learning and I couldn’t agree more.
That brings me to speak about my experience with encountering OpenAPI for the first time, how I relied on Stoplight as a learning tool for developing my projects, to better understand how the spec works as a developer.
But, Let’s Back Up a Bit
I should’ve introduced myself! Hi, I’m Roland; I am from Australia and currently completing my graduating year at university.
I got into web development two years ago outside of university because I had an innate interest in building things and a passion for design. I hope to one day bridge the gap between the technical world that developers thrive in and translate that into products that non-technical people can appreciate. If there’s one thing that can do all those things, it’s websites! Everyone uses them, and building a good website can be both elegant in code as much as elegant in front-end appearance.
How I Landed on Stoplight for API Design
Recently through my NodeJS learnings, I decided that it was time to step up and write some code that I actually had confidence would run as expected. This led me to Typescript, Jest, and TDD. When it comes to writing my APIs, I discovered the OpenAPI specification and all of its (sometimes daunting) complexity that made it scary to tackle as a first-time student developer.
While working on my project that required an API, I first naturally landed on the Swagger editor developed by Smartbear. But to me, this was just a glorified version of what I can already do inside my text editor.
I wanted a tool that was more abstracted while still letting me drop down to the raw YAML/JSON when required to both edit and understand how my endpoints are represented and something that gave a good API developer experience- Enter Stoplight!
As a Student, What Do I Value in a Good Tool?
I discovered Stoplight a few days after stressing about how I was supposed to understand all the mess that was trying to use Swagger! I may as well have been trying to digest an IETF RFC for my university which is not what I wanted to be doing.
On my hunt for tools, I picked out Stoplight from this list of open API-related software. I picked Stoplight because it checked all the boxes, and came with 3.1 support.
Another contributing factor that makes a good tool is Linux support. After some quick research, I was able to get Stoplight running as a universal App Image on my Debian computer, which I use for basically anything that isn’t video games.
In my initial experience, I had to go to the About tab and check that it was an electron app because I could not believe the performance that it offered! The dev team has done a great job creating a pretty-looking tool and I now bring Stoplight up as an example when talking with friends about how electron can be done right.
Unfortunately, a downside to picking Stoplight is that it’s SaaS and as a student with a love for my software being OSS, coupled with a budget of usually $0, you are taking a risk in investing your time into a tool that could become a paid platform or change in some way that invalidates your workflow. But at least for now and in the near future, the free plan with Stoplight is a great option for a student like me.
However, I can look past this because at the end of the day the output is an open-spec file that you can take anywhere. Mind you, that I am skipping over the auto-mock server features, but as a student, what matters more to me is that I can slowly grasp an understanding of the output produced.
Lastly, a good tool to me is one that is focused on one thing. What makes Stoplight valuable to me is that it does the one thing I need it to do, which is to help me produce as well-formatted OpenAPI spec for my projects that I can use to produce documentation for myself in the future, and it does it well.
What is Important to Me as a Student Developer
As a student developer, nothing is more important than being able to quickly grasp and absorb information. Keep in mind, not so long ago I did not do much of ANY software development, let alone decide to learn how to build an API to a specification.
I think many of the things that are important to intermediate developers can also apply to students learning and discovering tools, techniques, and languages for the first time. Some of those things fall into the following categories of importance:
- An important aspect of being a student is to be able to absorb information. After all my time learning JS and deciding to launch into these new tools, information overload, and burnout can become a real problem so it’s important to pay attention to time sinks and know when to move onto the next iteration.
- When I am learning, approachable tooling and simple plain English documentation are essential.
- When I have deadlines both between my studies, projects, and life obligations, being able to work quickly is important! For the “average” developer who just wants to get the job done and meet the business requirement, tooling is the MOST important time investment.
Stoplight in My Projects
My main use case for Stoplight is to create API documentation for myself in the future for my blog’s API which I am building in the NodeJS/express/typescript stack of software.
I use the form-based designer to create my endpoints. I then implement those endpoints, then write unit tests for them in Jest, rinse and repeat!
In the future I hope to get into mocking more for testing, I am already using SuperTest agent to test basic endpoint configuration, and I would highly recommend this to any other students who want to start their own web-based projects.
Let’s Talk
If you are a fellow student or developer who likes to chat about web development, or if you are hiring for a junior frontend/backend/full-stack position, please feel free to reach out to me over at Linkedin. And, if you want to try out Stoplight for yourself, check out their free plan and learn more about API documentation portals.
