Posts

At Oak City Labs, we rely heavily on unit testing in our quality software process. Unit testing is the safety net that lets us reliably improve existing code. Our testing suite double checks that modified code still behaves the way we expect. I’ve written before (here and here) about how we use dependency injection (DI) which makes unit testing easier. DI helps us wrap code we need to test in a special environment. By controlling the environment, we can make sure that the code being tested gives the correct output for a given set of conditions. This works very well for pieces of the application that we can encase in a layer that we control. Unfortunately, we can’t wrap everything.

Consider our API layer. This is the part of our application that talks to the server over the internet. It makes network calls, processes replies and handles errors like slow network responses or no network at all. In testing this code, we want it to behave as normally as possible for accurate testing, so we still want it to make API requests and interpret the results. At the same time, these are unit tests, so they should be fast and not depend on external resources. We don’t want to make requests to a real server on the internet. If that test failed, it wouldn’t be obvious if our code was broken, the server was down or the network cable was mistakenly unplugged. It’s important that our unit tests be self contained so when something fails, we know that a specific section of code has failed and we can fix it ASAP.

Back in the old days, before Swift, we wrote in Objective-C. Swift is a strongly typed language where Objective-C is weakly typed. While weak typing in Objective-C often gave a developer enough rope to hang themselves, it was flexible enough to do interesting things like easily mock pieces of software. Using mocks, fakes and stubs, you could (with some effort) replace pieces of the system software with substitute code that behaved differently.  We could use this to test our API code by changing the way the system network routines worked. Instead of actually contacting a server on the internet, a certain call just might always return a canned response. Our API code wouldn’t change, but when it asked the system to contact the server for new data, our mocked code would run instead and just return the contents of a local file. By building a library of expected calls and prepared responses, we could create a controlled environment to test all our API code.

Swift, on the other hand, brought us strong typing, which wiped out whole classes of bugs and insured that objects were always the type we expected. We paid for this safety with the loss of the ability to easily mock, fake or stub things. Someday, Swift might gain new features that make this possible (maybe even easy) but for now, this is difficult to do with any efficiency. So, we need a new approach for testing Swift API code.

Like we said earlier, we don’t want to use external network resources to test our code because too many things are out of our control. But what if the test server were running on the development machine? In fact, what if the test server were running inside our application? Enter two open source projects — Ambassador and Embassy from the fine folks at Envoy.com.  Embassy is a lightweight, dependency free web server written in Swift. Ambassador is a web framework that sits on top of Embassy and makes it easy to write a mock API server.  

In this new approach to testing our API layer, we’ll write some Ambassador code to define our mock endpoints. We’ll declare what URL path they’ll respond to and what response the endpoint will return. Now, inside our unit test, we’ll fire up the mock server and run it on a background thread.  Since you’re controlling both the client and server side of the request, you can make asserts on both ends of the exchange. On the server side, you can validate the data submitted by the client. On the client side, you can ensure that the response from the server was interpreted correctly. Ambassador has some nice conveniences as well for working with JSON data, introducing delayed responses from the server and other common testings needs.

In order to use our freshly built API mock server, all you need to do is change the server name used by the API layer. This is important because we don’t want to make significant changes to our code in order to test it. We want to test as close as we can to production code. By switching our base URL from “https://api.ourserver.com” to “http://localhost:8080”, we can test all our network requests with no external dependencies. Since we’re using dependency injection, this change is very simple to implement in our unit testing routines.

The move from Objective-C to Swift has allowed us to write cleaner and safer code, but the price we pay is the loss of the fast and loose, über permissive Objective-C runtime environment. Fast and loose always caused more problems than it solved, so I’m happy to see it go. A few of our existing solutions have gone with it, but with a bit of ingenuity, we can move forward with better and safer new solutions.

 

Oak City Labs is thrilled to announce the launch of CurEat’s Android app to the Google Play store this month! CurEat, a restaurant discovery tool, is the vision of entrepreneur Steve Mangano. We are honored to have partnered with Mangano to also develop both the CurEat iOS app and cloud server, which launched earlier this year.

The CurEat team will celebrate the launch, along with the introduction of their new CurEat Experience Program, this Friday, September 1 from 6-9 pm in Raleigh at the offices of Google Fiber. The Oak City Labs team will be there and we hope you’ll join too! More information can be found here.

Want to know more about this project? Download the CurEat case study below and we’ll serve up all the details!

CurEat is available in both the Apple App Store and Google Play Store now!

If you’re anything like me, you’ve spent an unhealthy amount of time perusing adorable cat GIFs on your phone, tablet, computer, tv and anything else that will let you get your fix of cuteness.

via GIPHY

In addition to browsing cat GIFs on every device I own, I can also check my email, listen to my collection of music, chat with my friends and even write blog posts! On every device I own I can access the same emails, the same music, the same chats, and the same text documents.

In a world where seemingly everything is connected, it is almost unheard of for a web app to exist without an associated mobile app, and vice versa.

Build Once, Use Anywhere

To reach so many diverse platforms, it is crucial to initially develop with the “Build Once, Use Anywhere” mentality. What do I mean?

Let’s say you want to create a program that lets you browse adorable cat GIFs (if you do end up doing this, definitely let me know!). You decide you want to build a website and an iPhone app, but also want to be able to add iPad and Android apps in the future. To “build once, use anywhere” in this case means building one API that knows how to talk to all of the apps, current and future, that you create, rather than creating an API for each app.

API

An API allows one program to interact with another. In this case, you would create an API that communicates between your cat GIF storage and the mobile and web apps people are using to view and upload cat GIFs. So, let’s come up with a few API commands you’ll want:

  • Create – Allows user to upload a GIF (Technical term: POST)
  • Delete – Allows user to delete a GIF (Technical term: DELETE)
  • Update – Allows user to change the name of a GIF (Technical term: PATCH)

For reference on the technical terms listed above, check out this article.

Now that we’ve defined our API commands, we need to create a way for apps to interact with the API. Both the device running the apps and the device running the API must be connected to the Internet. In this case, the API is part of a program that runs on a computer called a “server” which is connected to the internet.

Server

In computer science jargon, this project structure can be referred to as a “client-server model”, where one server (a program that runs your API) knows how to communicate with many clients (iPhone, Android, desktop, laptop, etc). If you want to learn more about the details of how a client-server model works, check out this article.

In reality, the server is just a computer in “the cloud,” which means it is just a computer connected to the open internet!

https://cdn.techterms.com/img/lg/client-server_model_1253.png

Storage

Now that your API connects your server with your apps, you need a database to store the cat GIFs that are uploaded. A database can either be hosted on a server of its own or the same server as the API. To keep it simple for this example, we’ll just say the database is hosted on the same server as the API.

The goal of the database is to keep it isolated so that only the web server framework running the API knows how to access the data. This keeps the data secure and abstracted in a way that only one device (the server) has to know how to access it instead of all the devices users have.

Takeaways

  1. If you’re looking to have a mobile app built, make sure the API is being developed with the “build once, use anywhere” mindset. This is one of the easiest money and time-saving decisions in modern programming.
  2. Whether you’re on a phone, tablet, computer or other device, if you’re using the same service (e.g. Google, Spotify, etc.) then you’re likely interacting with the same API to access that service on all devices!
  3. “Build Once, Use Anywhere” allows you to build the logic behind a service once and allow use of that logic from as many devices as you want (or can afford).
  4. If you build an awesome cat GIF app, make sure to let us know!

Since joining the team at Oak City Labs last year, I have had many conversations with friends, family and prospective clients about mobile app development. When I show them an app we’ve built, like CurEat, they often tell me that it looks great, and then ask me to show them which parts of the app I made. While seemingly an innocuous comment intended to allow me to showcase my hard work and reap some easy praise, this particular request typically leads me to release one of my patented <heavy sighs>.

But Cory, why do you heavy sigh at such a polite, ego-boosting request, you ask? Well, fellow human, I release the air from my lungs at a much faster rate than usual in an exasperated manner because users of our apps don’t actually see anything I have made. They see the work of the design team in the visuals of the app. They see the buttons, lists, login screens and settings menus that Jay (iOS) and Taylor (Android) have coded in. They even see the legalese a lawyer somewhere put together. So when I tell people that I spent over a year working on an app after explaining that there is no visual evidence of my work at all, they get this sort of half-confused, half-amused look on their face.

Of course, I could simply tell people that I am a backend developer who helped make the Python Flask server, PostgreSQL database structure, RESTful API and Angular webapp that allow the mobile app to be more than a sad, functionless, empty shell. This jargon only helps those with a technical background, and usually leads most others to say something along the lines of “Oh, OK…” when in reality, they’re thinking “Was he even speaking English?”

And so, through a long, arduous process of trial, error, confused looks and copious amounts of feedback, I have concocted what I believe to be the ultimate formula in explaining what my actual role is in the app development process.

To aid in understanding my role as a behind-the-scenes magician, I will refer to the Snapchat app as an example.

For those who aren’t familiar with Snapchat, let’s run through a typical Snapchat use case. This is assuming you already have an account and are logged in.

Step 2: Snap a super artsy picture of your keyboard and wrist rest

Step 3: Send it to your friends (Some names below may or may not be based on the many nicknames of Burton Guster)

Aaand we’re done! I have now sent a poignant photo of my keyboard to two of my closest imaginary friends. Soon, they will receive a notification of the photo and will be able to open and view it for themselves.

This is the process for using the app, but to understand how we are able to get to this point and do such a thing, we need to step back to the very beginning.

Here is the terminology I will use in the following examples:

  • Mobile Developer – Somebody who builds the actual app that a user sees on their mobile device
  • Backend Developer – Someone (like myself) who works on the behind-the-scenes details such as the server, API and web framework. If this doesn’t make sense, that’s OK – we’ll get there!
  • Snap – A snap is an image that you exchange with friends on Snapchat

When the app loads, you have the option to log in or sign up. So far, this is all the work of the mobile developer. They created this screen, pulled in images from the designer, added some text onto buttons, and bam. This screen is born:

Now let’s say you click Log In. You are then taken to this screen:

This screen lets you log in with your account information and takes you into the part of the app where you can actually send and receive snaps. Every “usable” thing on this screen was added by a mobile developer: the input areas for username and password, the “Forgot your password?” link and the “Log In” button. So far, the backend developer hasn’t played a role in either of the previous screens.

Now, what happens when you press the “Log In” button? Does the phone magically know whether your account info is valid or not? If that information were only stored on your phone, how would you be able to log into Snapchat on a new phone with the same account?

The answer: You wouldn’t. Your account information is not even touched by the mobile developers!

*My Time to Shine!*

There are a lot of behind the scenes details happening here that the backend developer is responsible for, so let’s break down the differences between the work of the mobile and backend developers in the above scenario.

Technical Breakdown:

  • Mobile Developer:

    • Create app screen with inputs
    • Send username/password to server
    • Receive output from server telling the app if the login was successful
    • Continue on to the next app screen if the user logged in successfully
  • Backend Developer:

    • Tell server how to handle a request to log in a user
    • Tell server how to check with the database to confirm/deny a login request
    • Tell server how to send a request back to the app if the user logged in

Non-Technical Breakdown:

The mobile developer creates the code for the login screen, the backend developer creates the code for all of the actual “logging in” and checking of whether you are a valid user or not.

Let’s go back to the scenario of sending a snap to your friends.

Starting with my super duper artsy photo again, we can examine this screen. All the interactions on this screen are completely up to the mobile developer. A few examples are the ability to save this image or add text to it. Now, let’s say the user clicks the button in the bottom right to choose which of their friends to send the snap to.

We’re taken to this screen. The app displays a list of names which are all of the potential friends you could send your snap to. You select the ones you want, then click the send arrow in the bottom right to send your snap to these friends. Everything visible is presented with code from the mobile developer still. Except…

Let’s back it up.

Where did your friends list come from? Does your phone just magically know which of your friends have snapchat and also have you as a friend? How would you add or remove a friend? And what are those numbers and emojis next to the stars on the right side of each name row?

That’s a lot of questions, so let’s do a breakdown like we did before.

Technical Breakdown:

  • Mobile Developer:

    • Request list of friends and friend information from server
    • Display list of friends
    • Display information about each friend (such as the numbers and emojis)
    • Allow the user to select which friends will receive their snap
    • Tell the server who the user wanted to receive their snap
  • Backend Developer:

    • Build a list of friends and friend information for the given user and return the information to the app
    • Perform the actual sending of the snap to all of the selected friends.
    • Notify all the friends that they have a new snap

Non-Technical Breakdown:

The mobile developer creates the code that displays all the friends and let’s the user choose who to send the snap to, but the backend developer creates the code that tells the app who the user’s friends are and the code that actually sends the snap to those friends.

At the end of the day, there’s a lot of communication that needs to happen between mobile and backend developers, because as you can see, they depend on each other very much. Without a mobile developer, all the backend logic and data and snap sending would be pointless. Similarly, without a backend developer, Snapchat wouldn’t actually be able to do anything. It might sit there looking pretty but you wouldn’t be able to send your snaps to anybody, which would be quite sad.

I hope my examples helped, but if not, here are a few analogies to provide more clarity:

Non-Technical Analogies:

  • A mobile developer is like a news anchor. Without the backend developer (teleprompter), the news anchor would just sit there looking pretty without knowing what news to tell viewers about.
  • Alternatively, think of a mobile developer like a grocery store, choosing how to display all of the food that the backend developer delivers. Without the shelves and organization from the mobile developer, all of the food from the backend developer would be too chaotic and unstructured to give to the shoppers. But, without the backend developer, there would be no food at all to give to the shoppers.

Technical Analogies:

  • A mobile developer creates your Gmail app, but without the backend developer, your email would never show up in the app.
  • A mobile (or web, in this case) developer would create the Netflix app or website, but without the backend developer, no shows would show up or be watchable.

 

It’s a three letter acronym that’s thrown around all the time, yet most non-technical founders and businesses gloss over the impact of an API, the value it can add to your business, and how it can help you in the future. We’ll start by covering what an API is and how it works.

What is an API?

API stands for application programming interface, and most explanations on the web want to explain a whole bunch of other things like clients, servers, JSON, etc. We won’t go into that for this article because often times it’s kind of boring for folks that don’t work with it everyday.

You probably have a ton of apps on your phone, so for this scenario let’s use Google Maps. When you open Google Maps and search for “grocery”, the app needs to get that information from somewhere.

While most new phones have a ton of processing power, the amount of data behind something like Google Maps is huge. Since your phone can’t handle all of the data for every possible thing people search for, the data needs to live somewhere else. Additionally, when Google needs to change or update the search results, they don’t want to push constant updates to your phone. So it makes sense for all that data, and all the processing, to sit and take place somewhere else. Usually this is in the cloud, often a service like Amazon Web Services, Google Cloud, Microsoft Azure, etc.

OK, so we know your phone needs to contact the cloud for some information but how does it know which cloud, where in that cloud and what info to get? That’s all a part of the API! The API has a URL just like any other web page. Therefore, when you search for “grocery” in Google Maps, your phone hits that URL in a special way and automagically serves up specific information about grocery stores to your phone.

As one of my former economics professors used to say in class, “So What?” The phone talks to a server (aka the cloud) and the server returns some information that the phone not-so-magically understands, how does that really help?

What does that mean for you or your project?

It means that your project’s API (the thing that magically serves up content so the app on the phone can operate) needs to be super well documented, well laid out and secure. It also means that time and attention should be devoted to correctly building it out. The API is basically a map for the app on your phone. If you also have a web app that matches, it will use the same API. If the API is poorly documented, you can expect some real problems both during development and afterward – making troubleshooting or sharing information a nightmare.

What does this have to do with business?

A large number of companies sell the data behind an API to other parties. Google, again, is a prime example. As developers, we use the Google Maps API quite a bit.

As a business you may not be thinking about selling the data, but what if you have integration partners down the road? For example if you’re building a CRM, what if people want to sync data between their app and yours? Or if you have a product in the healthcare space, maybe you’ll need to integrate with Epic at some point. You’ll need to not only understand your API but understand their API in order to be successful.

Other examples include the Facebook Graph API and Twitter APIs.  Both are open to developers to use for new apps. ProgrammableWeb has an online directory of APIs that are both free and paid. It’s worth a little searching if you’re building an app to see if you can buy versus build from scratch.

The API market itself is continuing to grow, including tools and servers around APIs. Take a look at two major acquisitions by Oracle and Google for API design, documentation tools and management services.

If you’re building an app, definitely consider the market potential for the API. Often, there is more long term viability behind the data and what others can do with the data versus the actual app.