This post is a transcript from James Lockwood’s lightning talk at
The Austin Homegrown API Meetup in August, 2019.
Hi guys, I’m James. I’m the developer advocate for Yuuvis. My job is to spread the word about our recently released Yuuvis API and also work closely with developers as they build their custom solutions out.
So, our API is built around information management. It gives you the flexibility to enhance an existing solution or to create your own custom solutions within points, so that you integrate, migrate, search and store structured and data such as contracts, design files, videos, chat conversations, and any file type your business uses. Our API is more than just another document repository like the S3 buckets or Dropboxes of the world.
What sets us apart is that we take in a document or object, we also take in a strongly typed metadata file that’s associated with that item. This metadata file gives the user the ability to perform different types of searches, including a full text search within the list of the documents. So imagine you’re working with a client and the client has a list of 1000 or more different invoices and you’re looking for all the ones from ‘Company A.’ With this a search, you’re able to do the full search on it and find all the documents that say ‘Company A’ on them, which is cool. So I was actually going to ask the diversity of the room, as far as developers go, but that was done earlier.
So we do know that we do have a good diverse group of developers here today, which is awesome. Myself, I’m a JavaScript developer by trait. And to be honest, in my free time, I’m doing a lot of things with WordPress, as far as freelancing goes for fun and projects and stuff. Because that’s what I’ve been able to find in Houston for free time. I also have a cute cat, her name is Poppy.
As we just demonstrated, developers code in a variety of different languages. For that reason, when companies decide to build out an API, you should make it possible for developers to reference that and use that API in various of coding languages. So when I first started with my company, we were using a product called Swagger hub. I think that was a Swagger tool [Mike Kistler] was talking about, to house your API. And if you’re not sure, it’s an integrated API development platform that brings together all the core capabilities of an open source Swagger framework along with additional advanced skills to build document, management and deploy your APIs.
“You should make it possible for developers to reference that and use that API in various of coding languages.”
Personally, I often got lost using this tool and I felt like it was always having to search for our API in the sea of all the other ones that were there. Also, it felt a bit clunky to me and it felt like it would be hard to build a community around our API with this tool.
So, I was pleased to learn that after our first hackathon, we decided to move to the Microsoft Azure portal platform. Now, I’ve used it in the past for hosting my server needs. But I’ve never used it for hosting an API. So I did some investigating into it and found that it’s a popular tool for developers to use for hosting their APIs. And it has some other cool features, such building a form inside of it. And then there’s also a way to handle tickets with it, I believe. And it looks pretty customizable too from what I’ve got to play around with.
So, I was recently added to the Octopus team, which is our documentation team at my company. I come out to events, talk with developers, and I also get to work with the documentation, which for me, I think is really cool. Because I get to make those connections outside in the world, and then I can actually answer questions for people, which is good.
So getting started out of the package, Azure portal came with JavaScript, Java, Python, Curls, C-sharp, Ruby, and I’m sure a couple of other languages that were built out for coding examples to our API end points. But we quickly found out that most of our developers that were using our platform, use the top three, which were JavaScript, Python, and Java. So for that reason, since we very freshly—just in July—released our API, we decided to close it down to just the top three languages that were being used.
We were able to take care of any bugs, fixed issues, any kind of surprises that came up. We figured let’s take care of them on a smaller scale before we have all these other languages to deal with.
So part of my talk is going to be on getting started. What did I do when I had to start working on documentation? And then the other part is what do you do when you don’t know the languages? So as I mentioned previously, I’m a JavaScript developer by trait. And our API had examples, currently set in JavaScript, Python and Java. So the one thing that excited me in my job was the documentation. I subsequently got very close and personal with our API. Initially, I was really lost for the first couple of months and just didn’t really understand what was going on. And there was definitely a language barrier for me and my company.
“But getting to test the examples out and make a lot of mistakes helped me out a lot.“
So getting started, I went with a trusty old Postman doing calls, checking things to see how they work. For me, I had to figure out, first how to store something. Since, like I said previously, when we POST something, it takes in that extra file with it and that’s called a multi-part POST request. So that helped make it so your items were sortable.
Next, I started my examples in JavaScript for which should be the easiest one for me since that’s what I code in primarily. Of course it was. I was able to work through it rather efficiently.
I did find some bugs here and there. I reported them as needed and I did run into… A big issue for me was dealing with cores. But I did figure out that we needed to run a node server. So I was able to make calls on my local host. Found a few typos, nothing major. All right. So the different languages is the other two, which were Python and Java. I really didn’t know how to use them. I’ve never touched them before. They seemed foreign to me. I was scared thinking about having to test something in a different language. So what did I do?
Well, I had a close personal teacher friend of mine, he’s one of my mentors. He says, “The first thing you need to do is see what it is. Why do you want to use a language or a tool if you don’t even know what it does?” So I consulted uncle Google.
I found out that Python is a jack of all trades, bad-ass program in language. It can be used for building both desktop and Web Apps. It also provides a functionality to take care of most common programming tests. Well, I thought it was cool. So, I start. I downloaded python version 3.7, all things that came with it. I definitely watched a handful of lynda.com videos, to get the basics at least and learn the syntax. Then I was lucky to find some in-person meetups, where I was able to learn some of the basics and get some questions answered. That definitely helped me out a lot too. So now I go armed with some good on the job training skills and I started testing. I use the Python terminal and Python IDE for all my testing needs. My team knew that I had never used this language before and were pretty supportive as well throughout my testing.
Lastly, as most developers know in coding, you need to try and not give up. Try and try again, try not to ask for help. You want to make sure you figure it out on your own. But eventually, you do figure it out. You finally realize out of all the areas, you need that little error in front of your requests to pull the document from somewhere, which is cool. I learned that. Moving onto the Java, I found that I also needed to find out what was Java. So I found out Java was developed to look and act like C++, but it’s supposed to be simpler to use. It enforces an OOP model and it can be used to create apps that run on single machines, meaning servers and over clients’ networks.
So my next challenge for me was testing the Java code examples. I will admit this one seemed a lot harder for me to pick up. And to be honest, I ended up having to get one of my team members to give me a 30 minute crash course on what Java was and how it worked and the ins and outs. They helped me to download my Java environment, and they helped me to set it up. I learned something that was called a Maven, and I learned how to use the IntelliJ environment for my testing needs. So that one was pretty clean-cut though. I was pretty fortunate, this tested well before I got handed the task of testing it. So, I mean, it was just dropping my code examples, hit submit, it compiled and it worked great.
So, what’s next?
Well, everything worked out. I was able to do my testing with my documentation—everybody went home happy. I will admit though that the best thing that helped me out the most was asking for help. You don’t know everything, because so many new things come out all the time. Just ask in your team, the worst thing they can tell you is no. So that was definitely the one thing that I learned about just doing API testing for the first time. Because I’m a front end developer. I’ve never done this really professionally before. So asking for help is the best thing.
View the full video and slides from James’ presentation.
Want to learn more about APIs?
Join us for our monthly meetup!
About Author
Leave a Reply