Hello! 👋 Welcome to the API Learner app. 🎒 By following the instructions below, you'll learn a little about how REST APIs work and make an open source project contribution at the same time! 💥
- We'll be using HTML and JavaScript in this tutorial but you don't need to know any syntax at all, you can just copy and paste, with a few edits to plain text.
- We will depend on a few high level coding terms like "method", "function", "parameter" as well as some Git / GitHub terms but don't worry too much if you don't know these yet, you should hopefully still be able to follow the tutorial to the end - if not please let me know. 🙂
Hang On - What is an API?
You'll see the term API used to refer to different types of resource, such as code libraries - in this tutorial we're dealing with REST APIs, which we use to manage access to data.
Imagine you had a shop 🏪 and wanted to access your database of product information from both a website 🌐 and a mobile app 📱 - you could create an API that would provide access to the product info and that you could call from both the site and the app. That way the API could handle the detail of how the data should be accessed and so on.
APIs provide endpoints to fetch and update data. In this app we're only using GET endpoints - these allow you to fetch data to display or use in your client app, but a real API will often have additional types of endpoint to add new data or to update existing data. In the shop example, you might have an endpoint that would return the current list of available products.
- Lots of existing REST APIs are available for using in your apps - check out the GitHub documentation for an example. The GitHub API is an example of a third party API, where you access the data from another organisation or service (e.g. GitHub). In this tutorial we're going to focus on building our own API, but playing around with existing APIs is another great way to get acquainted with how they work.
Hang On - What's this Open Source thing?
In an open source software project, you can access and repurpose the source code. This means that open source projects can be worked on by communities of people, and be remixed in all sorts of creative ways. They also make great learning resources if you're trying to get into coding, for example, you can see a ton of source code for software projects managed by organisations like Mozilla on GitHub.
Even if you become a developer and end up working on software that isn't open source, you'll likely be collaborating as part of a team, so you'll find a lot of the same skills and processes are involved.
OK let's get stuck in and learn about APIs by adding an endpoint and remixing an open source project.
The project we're working on is hosted on Glitch at api-learner.glitch.me but we're going to manage contributions on GitHub. In GitHub you'll make a copy of the project, work on your additions in your copy, test it out on Glitch, and then get it merged back into the original project back on GitHub. This means that future learners using the project will see your contribution, and the live version on Glitch will be updated to include your contribution too. 👀 🎊
You'll see the existing endpoints in the API listed in the project homepage.
Click the first one on the list to see the result (ok so it isn't very exciting, it just returns some text but it's a real Node.js / Express API that uses server-side JavaScript, honest 🤓). You're going to add one of your own that will also run on the server and return some data to display in the page.
First we need to copy the project from GitHub. Go to the Glitch API Learner repo and click Fork (sign up for GitHub if you don't have an account yet).
GitHub will create a copy of the repository in your own account - you can do whatever you like with this copy of the app and it won't affect the original, but later you'll submit your additions to be added to the original so that, for anyone using the project in future, it'll include your contribution.
With your fork of the repo open in GitHub, click Clone or download, and copy the URL (it should end with .git) - you'll paste it into Glitch next.
In Glitch, click New Project and choose Clone from Git Repo.
Enter the URL you copied from your GitHub fork and click OK. Glitch will create a new project, importing the content from GitHub.
Now you can play around with the API on Glitch and see the changes reflected in realtime (this is extremely cool btw 😎 normally you would have to deal with a convoluted testing and deployment process to see this type of functionality running live).
With the editor for your new Glitch project open, select the server.js file. This is the Node.js / Express code that makes up the API. You'll see the existing endpoints in there, each one looks a bit like this:
app.get('/benormal', function(request, response) {
response.send('writes code and words');
});
You'll be adding one of these to the app - let's take a look at the detail. The overall structure here is like this:
app.get(path, callback);
The path parameter is the name of the endpoint, so in the above example, this code will run when someone calls https://api-learner.glitch.me/benormal.
The callback parameter is what should execute when that path (and method - in this case GET) is called. In the example, the parameter is specified as this function, which in turn receives request and response as parameters:
function(request, response) {
response.send('writes code and words');
}
Inside the callback function, the app uses the response parameter to send something to the client. The client is whatever application is calling the endpoint - in the case of this Glitch app it's typically just going to be the web browser, so if you visit api-learner.glitch.me/benormal, you'll see the text inside the function written out.
Notes:
- You can also call the endpoint from other clients, these could be applications in which you call the endpoint from your code - you can try it in a terminal using this command:
curl https://api-learner.glitch.me/benormal. - You could use the
requestobject to retrieve info about the request if necessary, for example if you wanted to pass data from the client in the request parameters (such as a search query), or in the body if you were e.g. updating or inserting new data into a database.
As you can see, all the endpoint does is return some text - in a real API the code would probably be querying a database but let's not bother with that for now. 😇
Right, let's get your endpoint added - in the server.js file, copy an existing app.get function (all the way to the closing });) and paste it under the rest (you'll see the place marked with a comment). Change two things:
- The endpoint name,
benormalin the example - make it something that's likely to be unique to you so that we don't end up with duplicates, e.g. part of a domain you own (let's avoid punctuation symbols and just use letters). - The text between quotes in the
sendcall - change it to some interesting fact about you or whatever else you want to send back from the server.
Your addition should look something like this:
app.get('/youridentifier', function(request, response) {
response.send('an interesting fact');
});
Note that the example endpoints we're using return plain text, but often the data returned from an endpoint will be structured, with JSON and XML common formats you'll encounter when using APIs.
Add a link to your new endpoint in the app homepage - open public/index.html. You'll see the list of endpoints in there - add a new list item to link to yours. Include the endpoint name as the anchor (a) element href and include whatever text you want to appear as the link inside the anchor body. It should look something like this:
<li>
<a href="/youridentifier">name</a>
</li>
Check that your endpoint works by viewing the live Glitch app (click Show) and clicking your newly added link. If all goes according to plan you should see the text you returned in the JavaScript code..! 😁
If your endpoint doesn't behave as expected and you need help, create an issue in the original project GitHub repo and I'll do my best to help troubleshoot.
OK so you've got a lovely new endpoint added to the API - don't keep it to yourself! By exporting it back to GitHub, you can get your addition merged into the original app.
In your Glitch project, select Tools and choose Git, Import, and Export.
Click the Grant Access link to grant Glitch access to your GitHub repo. Follow the prompts inside GitHub to allow Glitch / FogCreek to access your account.
Once authorised and back in your Glitch project, open the Git menu again and select Export to GitHub and enter your GitHub username, followed by a slash, then the repo name.
If the export is successful, your changes should be added to a new branch in your repository named glitch. Refreshing your forked project page in GitHub should show the new branch, otherwise you can select it in the branch dropdown (which shows master by default).
Click Compare and pull request for your Glitch branch - you're going to merge the changes from Glitch into the master branch for your forked project (the changes from Glitch are not pushed directly to the master branch so that you, or other members of your team, can review before merging).
Make sure you have selected your fork (it'll begin with your Github username) with the master branch as base, and your fork with the glitch branch as head - later you'll be opening a request to merge your changes into the original repo but not quite yet.
Use the Base repository dropdown to select your fork of the original project.
The page will update to show you are going to merge one branch into another in the same project.
If you scroll down the page you'll see your added code highlighted in green.
Click Create pull request.
Your changes shouldn't present any conflicts so click Merge pull request (then Confirm merge).
Hopefully your merge is a success - feel free to delete the glitch branch.
Now your forked project master branch is up to date with the changes you made on Glitch.
You can now request that your new endpoint be added to the original repo so that the list in there keeps growing and other people see your work. You'll do this by opening a pull request to merge the changes in your fork into hackaye/glitch-api-learner.
In your forked project in GitHub, click Pull request / Create pull request.
With the original (hackaye) repo selected as base and your fork selected as head (master branch on both), click Create pull request.
Add a optional message and click Create pull request.
Your pull request will be opened! Once the reviewer has had a chance to check it out you'll hear back - hopefully letting you know it's been merged and is going to be deployed onto the original Glitch project..!!! 🎏 🎉
Thanks for submitting your endpoint to the project! 🏆
By working through this tutorial, you've learned a bit about how REST APIs work at a high level and worked through the basic contribution process for a collaborative software project (open source or otherwise) including Branching, Forking, and Pull Requests! 💪 💻 🎆
These are some of the key skills in being part of a developer team. 🚀 Next, why not build on what you've learned by exploring APIs and open source a little further: 🎓
- API intro article that goes into more detail than the examples we covered here
- More comprehensive guide to building a REST API that uses a database
- The Express guidance for a handy reference
- If you want to brush up on your JavaScript, the MDN docs are a great place to work from
- Tools like the Swagger Editor and Postman if you want to play around with existing APIs or document / test your own
- Open Source contribution guidance from Github
- Tons of API projects on Glitch that you can learn from and remix
Please feel free to use this project in any way you find helpful - I'd love it if you'd let me know about any cool things you do with it or report any problems you come across in the GitHub project issues!