Table of contents
Introduction
This is the 1st part of a tutorial series of 3 articles.
What's so special about this series?
This series is intended for both non-dev and newbie dev peeps. What makes this guide stand out is that instead of just teaching you what are the steps to do things, I'll also deliberate on why I am teaching you to do things in those ways in the bigger picture. Additional screenshots are included to guide you in detail.
How does this article benefit me?
As a developer, what is an API is probably one of the first few things that you might have to struggle to explain to your colleague, your friend or even your child (given how tech savvy kids are nowadays). The standard procedure could be to start off with the full definition of API - Application Programming Interface. If you can explain succinctly what each of these 3 terms are to your target audience, good for you. If you can’t, it’s okay!
In the bigger picture, APIs are intended to be abstracted so that they can be used easily without going into depth what they are or how they work. The main purpose of APIs is to serve specific resources. Some examples of resources that you could get from APIs are:
- Github API - for Github repos, issues, PRs etc
- Dev.to API - for Dev.to posts, author information etc
- Digital Ocean API - for Digital Ocean deployment resources and droplets
However, if you are just starting out as a beginner developer, the API documentation for APIs like these could be pretty daunting 😰
- APIs as such have been extensively developed, and there are just so many different types of resources that you can choose from. Choice paralysis can be a real issue if you are just starting out and you feel overwhelmed by the large number of options available for experimenting.
- For some APIs, there are also different versions, which you might accidentally use the version that does not offer the resource that you want. This could happen if you try to blindly follow StackOverflow advice that is upvoted but outdated.
- There are a lot of API documentation that do not come with examples, and this could be rather unintuitive for a beginner developer who does not have much experience in calling APIs.
- Worst comes to worst, the last updated version of the documentation is significantly behind the current version of API released or that there is simply no documentation available. This is pretty common for the following reasons:
- The repository is maintained by small groups of developers and so usually there is an internal prioritization of developing the API further before making the documentation publicly available.
- For open sourced APIs, a common advice by more senior developers is to just delve into the repository source code directly and figure out how to use it. This is where web project navigation skills comes into play 😂
Hence to make learning easier, more light hearted and fun for you, in this article, I will walk you through how to use a API with Postman with a fan-made API for Genshin Impact ✨
Why Postman?
Postman is widely recognized as one of the simplest developer’s tools for API development and testing. It is a tool that I am very grateful to be exposed to after suffering from memorizing curl commands and reading unformatted shell output. Postman has helped me to improve my efficiency in the API testing process by a lot (More on in Part 2 later)
Genshin Impact Nani?
Yes you saw that right! What better example API there is than one that lets you see cute waifu & husbando get resources that you can relate to?
It does not have a documentation at the moment, but we will learn how to test APIs and create documentation for it easily with Postman 🚀 Don’t worry, it's not complicated! Let's take a look at what we are building today with this API.
Prerequisites
Some basic HTML and CSS knowledge will be good. We will not go through what is a <div> or how CSS style the elements in-depth. Even if you don't know all of these, as you follow the hands-on steps, you will intuitively get what they mean or do! Then later on, you can go and read up more about them in detail.
How you will build the demo
To make sure that you are focused on learning the API aspect of the website, this website will be built with Vanilla Javascript, HTML & CSS, aka no frameworks! 🎵
Your learning and building process will be as such:
- Part 1 (this article!): You start off with an empty character profile. You will learn how to onboard yourself onto new web projects (this is an important skill especially if you happen to join web projects that have yet to establish proper onboarding procedures)
- Part 2: I will walk you through the Genshin Impact API to see what it offers and we will call it to get some data that you can use to populate the character profile.
- Part 3: After knowing where to populate the data in the HTML file, you will then learn how to dynamically populate the character profile using Javascript.
Summarised learning process
Learning Objectives Checklist
- [ ] Web Project Navigation Skills using the Browser Inspector
- [ ] Inspect Elements
- [ ] Inspect Network
- [ ] Debugger
- [ ] Learn to use Postman to
- [ ] Make requests to an API
- [ ] Make documentation for API and publish it
- [ ] Use the API data you retrieved to populate a simple website
Setup Instructions
-
Have Git installed, then fork the starter kit repository here. The fork button is found at the top right corner.
After forking, you will see your own
genshin-api-tutorialrepository under your account. Clone this repository. If you have forked it correctly, you can see your username reflected in the clone URL.
If you are a non-dev or just starting out as a dev, I recommend using the Github Desktop to clone it. After you are familiar with git operations, then you can learn the Command-Line-Interface (CLI) methods of calling git commands.
-
Postman
- Download the native software or use the web browser version of it.
- Both should work the same, but the UI would be slightly different.
Screenshot of Postman on MacOS. You will have a new collection by default.
-
Code Editor
- For this hands-on, you can use whatever you want, even Notepad ++ suffices because it is that simple.
- Personally I recommend Visual Studio Code for Web Development, because of how lightweight it is and easy to download appropriate plugins to aid your coding process. And if you do choose to use this IDE, here are some suggestions for plug-ins to install for this project.
- HTML CSS Support: Intellisense for auto-completion of HTML attributes
- Markdown Preview Enhanced: the scroll sync feature is very useful for markdowns.
- Markdown All-in-One: I greatly benefitted from the keyboard shortcuts for markdown & ToC feature from the plugin. There's also other nifty features you can checkout on the page.
Tutorial
Exploring the starter kit repository
👉 In every repository, always start with its README.md. It is where you can find information such as setup instructions and expectations for how the project works. In this repository's README.md, you will see a similar explanation as what the summarised learning process diagram has illustrated above. Now, open up the index.html in your browser. You'll see a plain character profile.
Instead of looking hard into the index.html and trying to understand how this is made, I'll teach you how to use the Browser's inspector to inspect this easily! ⭐
Inspecting Elements
-
Right click on the website and click on "Inspect Element", as shown in the screenshot below. I'm using Firefox Developer Edition for my browser, but any browser would have that option available.
-
Next, click the icon next to the Inspector tab. The icon will turn blue, and now when you hover over items, the hovered item will become highlighted in yellow/purple (depending on your browser theme). You will be able to see the position of the element in the HTML hierarchy tree in the inspector.
For example, in the screenshot below, I'm hovering on the
.right-columnclass element, and in the inspector tab, it is highlighted in grey. The element highlighted in blue is the element that you have clicked previously.
-
Something very cool you can do in the Inspector is to edit the text you see in the website directly with the inspector! Just double click on the value of the element, and you'll able to edit it. Try it and see it reflect instantly on the website ✨ Do note that this change does not affect your actual file. Once you refresh the page, that change will be gone.
If you want your change to be permanent, then you have to make the same change and save in the actual HTML file. Now let's try to fill the character profile!
Filling the character profile
Based on the instructions for using the browser's inspector, explore the website and try to figure out where to change the following values for populating the character profile:
- Name
- Description
- Rarity
- Vision
- Weapon
- Character Image
- Background - this one is a little hard, hint: check the CSS attribute in the inspector
As an example, I have filled in the data at the corresponding places in index.html with relevant information of my favorite support trap character.
Take note of the id attribute, in this project they are relatively simple to identify but in bigger projects, it will be much harder to identify specific elements by semantic names.
-
Name
<h1 class="name-header" id="name">Xingqiu</h1> -
Description
<p id="description">A young man carrying a longsword who is frequently seen at book booths. He has a chivalrous heart and yearns for justice and fairness for all.</p> -
Rarity
<div class="detail-container"> <p>Rarity</p> <p id="rarity">4 stars</p> </div> -
Vision
<div class="detail-container"> <p>Vision</p> <p id="vision">Hydro</p> </div> -
Weapon
<div class="detail-container"> <p>Weapon</p> <p id="weapon">Sword</p> </div> -
Character Image
<div class="char-image-container"> <div class="char-image-background"> <img id="character-image" class="char-image" src="https://api.genshin.dev/characters/xingqiu/icon" alt="Character Icon" /> </div> </div> -
Background in
style.css
.portfolio-container { ... background-image: url("./Liyue.jpg") // you can choose to change this to an external image source link as well }
This is the result after the changes.
Isn't it a lot prettier? Even without changing the original style, with more meaningful data, we can add more vibrancy to the character profile ✨
How about you? What values did you choose to input and experiment for the above? 🐣
- If you have filled the details above with gibberish, don't worry 🤣 That's part of the learning process! Never be afraid to be experiment, as mentioned in the Inspector you can do anything and nothing is saved. Your effort is still beautiful. Do take a screenshot for memory and if you're not too shy feel free to share it with me 😄
- If you play Genshin Impact, you would know what characters will be available - but would you actually remember the in-game description accurately? Well, I don't and probably can't 😆
Won't it be cool if you can retrieve this data without having to manually log into the game or go to another site to see every time we want to change the values? Well we can with APIs!
But before we move on, let's review your current learning objective checklist.
Learning Objectives Checklist
- [ ] Web Project Navigation Skills using the Browser Inspector
- [x] Inspect Elements
- [ ] Inspect Network
- [ ] Debugger
- [ ] Learn to use Postman to
- [ ] Make requests to an API
- [ ] Make documentation for API and publish it
- [ ] Use the API data you retrieved to populate a simple website
We are now one step closer in finishing the checklist! ✨ Good job coming so far! Now, I'll show you briefly how the fan-made Genshin Impact API works before we end the article.
Intro to the fan-made Genshin Impact API
Go to the repository and briefly look at its project structure. You can skip the parts on the README.md after Prerequisites. As mentioned in the README.md, you can visit the API site at https://api.genshin.dev/, you will see this is what you get.
on Google Chrome/Microsoft Edge
on Firefox Developer Edition (yes this is one of the reasons I prefer this browser for web dev)
The result in the Firefox Developer Edition browser may look a lot more formatted and clearer as compared to the other browsers but no matter which browser you use to go this site, you are still getting the same data.
The data format of { key: value } is known as a JSON, and this case
{"types":["artifacts","characters","domains","elements","materials","nations","weapons"]}
the key is a string of "types" with value of an array type containing 6 strings. You can copy this data into a JSON prettifier to view the formatted result. This data tells you what type of resources are available in this API.
- But why are you getting this data just by visiting the API site?
- And how do you get more specific resources?
Hint: you get what you ask for - literally. 😆
🎶 I'll leave the questions for you to ponder for now, Part 2 will address these as well as the Postman portion.
Conclusion
Thank you very much for staying through Part 1 of the tutorial series! 🌟
Leave a heart 💌 and a unicorn 🦄 if you enjoyed it! And please, I would love to hear feedback from you! Be it about my writing style, how the tutorial can be improved, or your feelings after going through the article, share with me your thoughts by leaving a comment below 😄
Stay tuned for Part 2!
Top comments (0)