APIs, the building blocks of software, run our world. They're how software systems communicate with each other, and how we as people communicate with software. Knowing how to build an API is not only a crucial skill for a software developer, but a foundational part of general coding literacy - a skill that can help anyone in their career.
In this tutorial, you'll learn how to build an API directly from your web browser - no other tools required - using code.xyz, the online API editor. Whether you're new to software development or a veteran looking for faster ways to ship code, I'll demonstrate how quickly you can build a working API with code.xyz. We'll use code.xyz to build a fully functional SMS service that integrates AscenDB's Peaks API for identifying mountain information and MessageBird's API for sending SMS messages.
This service receives the name of any mountain and responds with that mountain's elevation and prominence. AscenDB's Peaks API provides data on over 7 million peaks worldwide - you can check out their docs on StdLib here. You don't have to be an avid climber find this tutorial useful, you can replicate these steps with any API of your choice to create your own SMS service!
What You'll Need Beforehand
1x US Cell Phone Number
1x Creative and Daring Soul
Step 1: Get Started with Code.xyz
The first step is to head over to https://code.xyz/. code.xyz is an online API editor built by the team at Standard Library - an embeddable development environment for easily building APIs, webhooks, and workflow automation tasks.
On the bottom left corner of code.xyz click (sign in). If you have a StdLib account click Already Registered and sign in using your StdLib credentials. A module will pop up prompting you to claim a namespace (this is your username). Input your e-mail and choose a password.
After you create your account, a different module will appear listing the subscription plans. A free account is all you need to get started, but you can read more about StdLib's pricing packages here.
Once you click Subscribe + Earn Credits you should see a confirmation message pop up.
Click Continue to return to the code.xyz landing page.
Step 2: Interact With Your First API on Code.XYZ
Click New API (Blank)
Enter a name for your API. For the purposes of this tutorial I suggest you name it MyFirstAPI and hit Okay (or press enter).
Once you hit enter, you'll see a service project scaffold on the left sidebar (a folder tree view) that has been automatically generated. At this point, you may have noticed that there's a "hello world" Javascript function inside (main.js).
To test your function simply click Run on the bottom right corner:
Clicking "Run", turns your function into an infinitely scalable API endpoint in just a few seconds! Under the "Results" area you will notice a documentation portal - copy and paste the URL into a new tab in your browser to see your API's information on StdLib. You will also see an API endpoint URL, copy and paste it into a new tab in your browser to see your "hello world" live.
Step 3: Replace the Default "Hello World" Function & Set Your STDLIB_LIBRARY_TOKEN
Now let's create our SMS service that will text back the elevation and prominence of any mountain peak. First, we will replace the default "hello world" function in the main.js. Copy and paste the following code that I have provided you with into the main.js file:
Once you paste the code into your main.js file, you will notice that your dependency on lib (the require('lib') line) is automatically added, there is no need to run an npm install through your terminal - code.xyz will automatically modify your package.json file and install any npm packages into your service directory.
If you look through the code I provided, you will notice that the definition of lib contains a process.env.STDLIB_LIBRARY_TOKEN environment variable. We have to add the required token to the env.json file to get our service working.
Navigate to the env.json file (click env.json in the tree view on the left), there you will see "dev" and "release" environment's waiting for you to input your "STDLIB_LIBRARY_TOKEN".
Place your cursor in between the quotation marks (see above screen) and either right-click and select Insert Library Token... or use the shortcut ⌘ + K.
Select Library Token to fill in both dev and release environments.
Make sure to save the changes with '⌘ + s' (or hit Save in the bottom right).
Step 4: Claim Your Free SMS MessageBird Number
We are almost there! Next, you will claim your free MessageBird phone number. We will use the MessageBird SMS API to send and receive text messages. StdLib makes it really easy for you to initialize a number, send and receive messages.
Keep code.xyz open. In a different tab, navigate to the MessageBird Numbers API on StdLib and accept the terms of service (the orange bar at the top).
After you've done that, you can claim your first number directly from the browser! Scroll down the page to the available method on the numbers API:
Currently, only Canadian and US numbers are available - choose the appropriate country code based on your location (if you'd like to see a specific region or country added, e-mail us!). Select one of your StdLib tokens from the dropdown to the right (it should say Unauthenticated) and press the Run Function button to see a list of available numbers.
Copy one phone number from the list, then scroll down a bit farther to the initialize method.
The initialize method of the API will claim an initial phone number for personal use, and is free. Enter the number you copied above into the number parameter input, pick a token from the dropdown next to run function, and press "Run Function" to claim your number.
Congratulations! You've successfully initialized MessageBird on StdLib! You can test this by sending a text message using the messagebird.sms service. Navigate to the MessageBird SMS API reference and try the create function with your personal phone number as a recipient - you should receive a text message from the number you've just claimed!
Step 5: Testing Your Service from Code.xyz
Now that you have claimed your free number, we can test your SMS service.
Return to the main.js file located inside your "MyFirstAPI" service. We will be filling in the section requesting parameters located on the right sidebar. MessageBird passes in four parameters to an SMS handler. These are the MessageBird number receiving the message, which will be the number you claimed earlier, the outside number that sent the incoming message, the contents of the message, and the time the message was sent.
sender: Your cell phone number that will receive the text
receiver: The StdLib phone number that received the SMS
message: The name of the mountain peak you are requesting elevation and prominence info. (e.g. Denali)
createdDatetime: Date when the SMS was sent
Click Run.
Within seconds you will receive an SMS text from your previously claimed MessageBird number.
Pretty neat huh? But we aren't done yet! Now that your service has been created, we will set it as a handler for the MessageBird telephone number you previously claimed.
Step 6: Set SMS Message Response Handlers with MessageBird and StdLib
When you set your service as a handler for the number you just claimed with MessageBird handlers API, it will trigger whenever that number receives a text message. We will use themessagebird.handlers.sms.set API method. You can do this directly from the browser! Head on over to https://stdlib.com/@messagebird/lib/handlers/.
Scroll down until you see the two parameters number and identifier
Number: The MessageBird Number you claimed in step 4
Identifier: .MyFirstAPI@dev
After you input the required parameters click Run Function.
And that is it! To test your service send an SMS message with the name of any mountain to your MessageBird number. You should receive a reply within seconds!
You can customize the handler to run any kind of code you'd like - and text back responses from other APIs. Just install whatever npm packages you need and modify the functions/main.js handler with whatever logic you want. Your SMS service is ready to test!
Suggested Step - Clean Up Your Code
The default sample API package (blank) may have some extra endpoints and files that you don't need (like anything in the functions/ folder aside from your main.js endpoint)- you'll want to clean these up eventually. To remove (and otherwise manage) files in code.xyz, right click on the file or folder you'd like to remove and click Delete.
That's It, and Thank You!
Thanks for reading! I am excited to see what neat services you come up with to add to Standard Library. You can replicate these steps with any API of your choice to create a cool service like this crypto price checker!
I would love for you to comment here, e-mail me at Janeth [at] stdlib [dot] com, or follow StdLib on Twitter, @stdlibhq . Let me know if you've built anything exciting that you would like StdLib team to feature or share - I'd love to help!
Top comments (0)