Web apps that work offline and sync using React, Redux, and PouchDB

I gave a presentation at the Boise Frontend Developers meetup this evening about web apps that work offline and sync using React, Redux, and PouchDB.

Here is a brief description:

We design our web apps and mobile apps differently.  We almost always need to design mobile apps to work offline.  Yet, we rarely think of our web apps working offline.  This leads to multiple code bases that handle state differently and work differently for users.  Adding offline capability to a web app becomes a gigantic effort and not feasible.  The sync process between multiple devices on multiple platforms is not easy either.  I propose a straightforward open source solution with React + Redux using PouchDB/CouchDB.  Full sample code and ready to use off the shelf libraries will be demonstrated.

Here are the slides for the presentation.

A link to the Github repo at jrzerr/react-redux-pouchdb

Angular 2 with ngrx/store

We've recently been working on a couple different Angular 2 projects using ngrx/store, a way to design your app with a central store for all of your app state similar to Redux.  To share some of our experiences, I gave a presentation at the Boise Frontend Development meetup.

Here is a link to the Angular 2 ngrx/store presentation slides and the Github repo demo branch.

State of Angular Presentation

This past week, Andrew Chumich and I gave a presentation on the State of Angular at the Boise Frontend Development meetup.  Covers our observations from ng-conf 2016 and some of the exciting features we learned about, and new projects in the Angular ecosystem that are going to be significant.

Some of our favorite new Angular 2 features are:

  • ability to control the View Encapsulation of a component, allowing you to use Shadow DOM to encapsulate styles, or use the default emulated mode to accomplish the same without Shadow DOM by compiling your styles/template differently
  • RxJS brings full-featured Observables into Angular 2, which is an alternative to using Promises and will enable optimized change detection for components

A couple of our favorite new projects in the Angular 2 ecosystem are:

  • NativeScript - using the same general techniques as React Native to have the possibility of creating hybrid mobile apps using Javascript but using Native UI components
  • Angular CLI - a command line interface for Angular 2 to launch new projects and add parts

Here is a link to our State of Angular presentation

Boise Code Camp 2016 Presentations

This year at Boise Code Camp I am presenting on a couple different topics.

One is on AngularJS Fundamentals, get the slides.

I discuss the fundamentals of creating web applications with AngularJS 1.x, covering topics of modeling your data, creating templates, designing directives, all work included Plunker code samples for you to run and try out.  Also includes strengths and weaknesses of Angular, comparisons to React and Angular 2, and what kind of software you can build with Angular.  Here is a link to this presentation on the Boise Code Camp Lanyrd site.

My second talk is Adventures of a Freelance Software Developer, get the slides here with no presenter notes, and here with presenter notes.

If you have aspirations of being a freelance software developer, come learn from my experiences of running my own freelance business over the last 7 years. I will share things that worked, things that didn't, what tools I use, how to market yourself, how to pick technologies to focus on, how to manage projects, and many other things that most don't think of when jumping into the freelance lifestyle.  Here is a link to the presentation on the Boise Code Camp Lanyrd site.

Hope to see you all at the awesome event!

Addition to AngularJS Component Refactoring Presentation

After creating my initial AngularJS Component Refactoring presentation, which explained how to refactor your Angular 1.x apps to use component-based design, there were some new developments in Angular that fit nicely as a next step. Angular 1.5 was released, which added a component function that is basically a more simple form of a directive like we refactored to in the presentation.

Angular 1.5 adds a logical next step for us to get to a component based design, and even closer to making an upgrade to Angular 2 much easier.  Angular 1.5 also adds a one way databinding type, but it doesn't work exactly like I hoped, I covered that in the updated presentation, too.

I updated my slides that I used during the presentation at the March Boise Frontend Developers Meetup.

AngularJS 1.x Component-based Design

With all the talk about Components being the future of the web, and frameworks like React and Angular 2 using them so prominently, why do we have to wait? Why can't we start refactoring our Angular 1.x apps right now to use the new design practices in these up an coming frameworks? Well, we can take some baby steps towards refactoring our Angular 1.x apps to take advantage of a Component-like design.

I gave a presentation about this topic at the Boise Frontend Development meetup in February.  You can get the slides here.

The presentation has links to three separate code demos, all hosted on Plunker.

React + Redux Design Lessons Presentation at Boise Frontend Development Meetup

To gain more experience building with React + Redux, we are building a time tracking web app based on the TSheets API and sharing our experiences with our developer community here in Boise.

We have built other TSheets API apps in AngularJS as a part of paid client work that we do at Zerrtech, which is Andrew Chumich and I, Jeremy Zerr.  Given that experience, building something similar to a previous project in another framework is be a great way for us to compare AngularJS to React + Redux.

Ultimately, we hope to understand those critical differences and similarities between the frameworks and approaches to designing web applications.  It will make us better advisors and more well-rounded front end developers.  Every framework we work with, and every project we complete, helps us reach these goals.

We decided that it could be beneficial to others if we shared this process with our fellow colleagues in the community.  We presented a few design lessons we learned at the Boise Frontend Development Meetup.  We hope to follow up soon with more lessons learned.  All of the source code is released on Github.  Here are the links to the materials from the presentation:

React + Redux Design Lessons Learned

PDF Slides

Github repository react-redux-tsheets-app

If you have any challenging projects that you need some contract help on, and like to work with people who are passionate about what they do, we would love to hear from you, reach out to me on LinkedIn.

AngularJS Guest Lecture at Boise State University

It's never too early to learn AngularJS. I am giving an AngularJS guest lecture at Boise State University for the Enterprise Web Development class

The link to the slides used in my presentation is here.


AngularJS Promises Presentation and Demo Code

I made a promise to present about AngularJS promises to our Boise AngularJS Meetup, and I resolved that promise. (sorry for the bad attempt at programmer humor)

Here is a link to the presentation slides as a PDF.

Included in the presentation were three separate Plunkers showing different variations of implementing an Image Preloader to show how to use several features of AngularJS promises.


Must-Have Features For Your Client API Library

The hard part is done.  You built an API for both you and your customers to use.  You have started to see some great partnerships from customers and other companies who are using it.  Now you want to get the word out about how your API can help people run their businesses more efficiently and help them make more money.  Is marketing the answer?  It’s a piece of it, but is also comes down to how easy is it for developers to integrate with your API.

The answer: Your client API libraries.

Designing a client API library for several programming languages can be a great opportunity to encourage developers to use your API.  Since your API is part of your product, and your product makes you money, I see a well designed client API library as a money maker.  It can allow you to keep current customers happy and find new customers in business sectors that might surprise you.  Yet, this is a largely under-appreciated aspect of many businesses that provide APIs.

As a part of my startup Affiliate Linkr, I currently integrate with APIs from 5 different affiliate networks, and none of them have a client API library.  That’s right, none of them!  Talk about a missed opportunity!  I wonder how many cool apps could be developed if only they would make it easier for a developer to pull some code off of Github and start innovating.

With my experience developing Affiliate Linkr and several other projects, I’ve had a chance to use client API libraries and create some of my own, so I wanted to share my opinions so we can all do a better job creating them.

If you are excited about creating a client API library for your API, but would like some help, please contact me on LinkedIn and let’s work together!

Here is a list of 13 must-have features when designing your client API library.

  1. Object Oriented Interface
  2. Throw Named Exceptions
  3. Allow Automatic Retries
  4. Should Handle Multiple API Versions Within One Code Base
  5. Base API URL Can Be Changed
  6. Unit Tested and Functionally Tested
  7. Use an Existing Library for Doing HTTP Communication
  8. Ability to Get Raw API Responses and API URL Calls for Debug
  9. Example Code
  10. Live Demo of Example Code
  11. Library Should be Installable Using a Package Manager
  12. Make Releases
  13. Quality Documentation

For a detailed look at each of the must-have features listed above, please read on.

Object Oriented Interface

One of the main reasons you are creating a client API library in the first place is to give people an easier way to work with your API.  You want to make it easy for people to create apps using your API, so you gain new customers or make your existing ones even more satisfied.  An object oriented interface to your API allows you to fit into the most designs, as almost all developers are familiar with OO and most likely their end application can easily integrate object oriented code.

One important detail when designing your object oriented interface is the naming of your classes, class accessor functions and other methods.  Your class names should correspond to the different service endpoints.  Like if you have a /users/:uid endpoint, you should have a UsersService that returns the user data as a User object.  If one of the resources you can access for a user is projects by an endpoint like /users/:uid/projects, you should have a User method of getProjects() that corresponds to this endpoint.  Internally, that function could use the ProjectsService class to fetch the data.

As with any class, module, or library, make sure you use a namespace so that you do not run into any conflicts with other libraries or existing code.

Great naming can help give your API users intuition about how to use your API without knowing all the little details.  It is also important to document how this naming will be done.  Let’s say that you have an endpoint of /users/:uid/equipment-owned, how would that look?  I suggest having a clear naming conversion guide, something that states for example:

  • dashes and underscores are removed and considered as word separators
  • camel case will be used (capital letters used for the beginning of words)
  • get and set will be used for accessors

A naming convention like this would result in the OO method being User->getEquipmentOwned() for the /users/:uid/equipment-owned endpoint.  Having a clear naming policy makes your job easier, and also helps future developers implement changes to the client API library easier when the API changes.  The specifics don’t have to match what I have said above, but having a clear naming convention is where the value is at.

Throw Named Exceptions

Your client API library should throw named exceptions for as many error cases as you can.  The names of the Exception classes should be self-descriptive, so inspecting an object in the debugger will allow you to have an idea of what is going on.

Your exceptions will break down into a few groups:

  • Authentication related
  • Authorization related
  • Request related
  • Response related

Make sure to cover them all.  They are especially important when a developer just starts to learn to use the library, where onboarding someone smoothly to your client API library can really improve how that developer feels about your company.  Yeah, I think of a client API library as a recruiting tool.

An example of this would be if the user sets an invalid API key, the API might respond with a HTTP status code or an error data structure.  You would present the user with this within your client API library as an exception thrown that would be descriptive and identify the error uniquely, like InvalidAPIKeyException.

Having named exceptions are also very important to allow multiple catch blocks to look for specific exceptions by name, so the user of the client API library can integrate error handling into their application.  Maybe some Exceptions thrown are fatal to the application, but other Exceptions just require a retry of a request.  

Having errors that can be recovered by just retrying a request is something that happens to me with a couple of the APIs that I use within Affiliate Linkr.  The API errors are random, really have no reason for them, and the same request will return fine with a retry, so knowing what particular error I got can be the difference between a fatal app failure and a smoothly running app.

Allow Automatic Retries

Not every API is perfect.  There could be situations where the API gives a bad response, or is too busy and cannot service a request.  Some of the reasons may be out of your control too, like a spotty internet connection that maybe broke down along the way.  Having a backup plan for these cases is smart.

I suggest to build in a way for the user of your client API library to enable automatic retries.  The reason I like it as an option for the user to enable is that maybe the user’s application has a different way they want to handle it.  Maybe they want to treat it as a fatal error, and possibly put some analytics on it so they can feed back to the API support team.

I feel like adding automatic retries might be better handled in your user’s application in most cases, so whether you choose to have automatic retries as a feature might depend on what your API functionality is.  Some APIs might be more prone to errors, or high traffic, where an uncaught error might be common and the consequences could be pretty bad.

The essential factors in a retry system is to allow configuration for:

  • Retries Enabled
  • Number of retries
  • Time between retries
  • Named Exceptions that will allow retries
  • Named Exception thrown when all retries fail

Depending on how much control you want as the designer of the client API library, you may want the Exceptions that will allow retries to be controlled by you and not exposed to the user.  However, I think that the goal of being developer-friendly should result in us exposing that as a setting, but providing a solid set of defaults so that it likely never has to be changed.

Having a different Named Exception thrown when all retries fail is important so that the application can operate with both retries enabled and disabled, but use the same code.  They could handle the non-retried Exception one way, maybe with manual retries, but the retry failed Exception might cause a fatal app error.

Should Handle Multiple API Versions Within One Code Base

When a new API version is released and some of the changes are not backward-compatible, developers using your client API library should not have their applications break.  Forgive me for stating the obvious.

I also feel that as a developer using the client API library, my existing code that uses the library should not break if I update to the latest library release.  This means that if I want to keep using my current version of the API, updating to the latest library release should not automatically cause my code to start using the newest API release.  I should always have a way to make my existing code continue to work.

To enable this, the client API library should have a setting as to what version of the library to use.  I don’t suggest that you make people define a number, like setVersion($newVersion), too much chance for error.  It is better to have a specifically named version method, or at the very least, a constant.  So setVersion3() or setVersion(API_VERSION_3).  If you allow setting it via setVersion(), just make sure you make sure it is a valid API version number and throw an exception if it isn’t.

Also, I suggest defaulting the client library to the use the current version of the API, but only using something similar to a constant API_LATEST that you can default to, and possibly a setVersionLatest() method.  Require this line to be in code!  This makes the developer make a specific decision to be working with the latest API version the library supports.  So then when they update to a newer release of your client API library, it will automatically point to the latest API version, and use any new code associated with it, and possibly cause breaking changes to their app but it was their explicit choice.  The key is that it is obvious that they are choosing to live on the edge by having an intentional choice they have to make.

To allow different API versions to be handled by the same code base, I like to design using Data Mappers to map between the API response and the client API library classes.  Data Mappers help with decoupling, because they are the only class that needs to know both about the API response data, and the client API library object.  As an example, I’d use a UserResponseMapper to map a UserResponse object into a User object.

Different class names for your service objects that correspond to different versions are the way to go, but a smart idea would be to inherit from a base service name.  The service probably doesn’t change a ton over time, but just small changes, so it’s likely that a base service class could have most of the logic you need.

An example of this would be if you are currently on version 1, but you come out with version 2, then your user class name for the latest version of the library would be User, but your old user class could be named UserVersion1.  Always keep the version number out of the class names of your current code, that allows you to potentially remove legacy code someday.  While the class names returned might be different than they were before, the interface is the same.  To handle this gracefully, it is useful to have a factory method to return an object that corresponds to your current API version to avoid having class names hardcoded.

Base API URL Can Be Changed

To allow for development work and testing, having the base API URL be a setting of the client API library will enable this to be easy.

This is also a key for unit testing.  You may want your live HTTP testing to go to a test-only URL that has some fake data in it.

Note that this base API URL should NOT include a version number in the path.  Most likely, the API version will be included in the URL, but the API version can contain any number of significant changes both in the API and the client library operation.  We are setting the API version separately also, as mentioned previously.  We will use the base API URL in combination with the library version plus the service endpoint to craft the full URL.

Normally, this base API URL would default to your production URL, but since being able to override the URL is a feature that you will want anyways to allow future development and testing of your client API library, it’s a no-brainer that it needs to be a feature.

Unit Tested and Functionally Tested

Like any piece of code, a client API library should have tests on several different levels, both unit and functional.  This can get a bit tricky since the client API library is meant to interact with the live API over HTTP.  Yet, it is important to have some tests for your client API library without needing the live API.  This is why I see a couple different levels to testing a client API library.

The first level is without any live API available.  The strategy with this is to mock the HTTP responses that the API is supposed to return, which then allows us to test all of our code independent of the API being available.  What this will look like is that we will have a bunch of files that contain sample XML or JSON data that is exactly like what is returned from the real API call, then we process it as though it was real.

The second level is with a live API available.  This part can be hard as you need some real user credentials.  You could consider having a dummy user that has some fake data within your live API.  One alternative is like Amazon Web Services PHP SDK, they just have a place within their client library that you can put your actual credentials in a file.  If your actual credentials are defined, then it enables running through the live API tests.  I really like that technique, because it avoids having to always maintain a dummy user account.

I would advise verifying the raw data back from the API as it’s own suite of tests, then also test the whole system together that is raw API data all the way through your client API library and converted into usable objects.

For completeness, you should also test for proper exceptions thrown when you pass in invalid API keys or client key/secret during authentication.

I think it goes without saying that we all know what we should test, but that ends up being a TON of work.  It’s easy for me to say in a blog post that you should test all this stuff, but of course it depends on your project and factors such as longevity, how many users you will have, and number of different environments the client API library could be used in.

Compare a Javascript client library to a PHP client library.  A Javascript library can be used from a node.js app, a web app using jQuery or other frameworks like AngularJS and Backbone.js, or a Google Chrome app, a mobile app, etc.  A PHP library really has a much more narrow focus, will be used from PHP code and possibly from within frameworks like Symfony or Zend Framework.  The end system is a lot more well known and predictable for PHP when compared to a Javascript library.

Use an Existing Library for Doing HTTP Communication

When writing a PHP client API library, I highly recommend using Guzzle.  Using that makes it very easy to mock HTTP responses, and knows how to talk OAuth to make communicating with any API require a lot less code.  Always strive for less code.

Other languages might not have a frontrunner in the area of HTTP communication libraries, if not, no big deal.  You will just need to implement the HTTP mocking yourself through smart design, and handle your specific HTTP authentication method, which for some APIs is probably not too hard at all.

Ability to Get Raw API Responses and API URL Calls for Debug

When I develop a client API library, as with other software, unpredictable things can go wrong.  When things go wrong, I start debugging and look to verify what is happening at the most basic level, which is the HTTP request and response.  If the client API library does not allow a developer visibility into this low level of HTTP requests and responses, it makes it so hard to tell what is happening.

The client API library should make it easy to get out raw API responses and API URL calls along with headers and body to help provide this low level debug capability.

Another reason to provide these raw HTTP request and response details is when dealing with support requests to the API provider.  When communicating with customer support, they always ask for the HTTP request and HTTP response, they don’t want to deal with your code and they shouldn’t have to.  If you give them the HTTP request headers, URL, and body, then they can re-create the request and see if what they see matches what you are seeing in the raw HTTP response.

This is not only for problems caused by your client API library.  No API is perfect, there is always the possibility for real errors in data to be caught by users of the client API library.  Our job as creators of that library is to enable the developers using it to identify these problems and easily have the information at their fingertips to debug it.

Example Code

ALWAYS include example code that uses your own client API library.  This should be included within your code base, and have instructions how to run it.  You should try and include examples from as many end environments as you can.  As an example, Javascript can be run in a lot of different environments, so you might need to consider example code for node.js, a web browser, and a Chrome app.

This example code can really inspire someone to create a cool app with the API.  Also, when things go wrong, the first thing I look for in a client API library is some code that I know that works, then see what I am doing differently.

I also recommend having a simple example, and some more advanced examples.  The more examples you can provide, the better off your users will be.  Look at what you are testing within your unit and functional tests for ideas on what kind of examples to create.

Live Demo of Example Code

We want to ship our example code with our client API code base, but it also is so nice when we can create live working examples of our client API library in the form of an application of some sort.

For a PHP or Javascript library, the goal would be to have a web page that developers could visit to test out the API using your client API library.  It would have a way to enter credentials to authenticate, then have form inputs to define the request parameters, and return the data from the API.

This is not only for seeing how your client API library works, but also is a great tool for testing out API calls.  You could include this sample web app in the client API library repository, but a better idea is to include it in a separate repository that you make sure to link to within your client API library documentation.  The reason to have it separate is that it should also be easy for someone else to spin it up and use.  The sample app would have a dependency on your own client API library, and if you are using a package manager, it’s a great way to show how that integration works too.

Library Should be Installable Using a Package Manager

For modern software development, it is a great idea and expected to have your library installable through the package manager for the language you use.  Like Bower or NPM for Javascript, composer for PHP, gem for Ruby, etc.

There are a lot of other aspects of your library that this implies, such as maintaining releases and versioning of your API to be compatible with the package manager.  You will probably have some extra config files that are a part of your repository.

Make Releases

Using a package manager will dictate most of this process for you, but define your release procedure and naming convention, don’t just make everybody pull trunk.

If I look at a new project and see no releases, I automatically think less of the project, consider it to be in a beta state, and will start to look for alternatives.  So make releases so you give your users confidence in using your library.

This also helps when it comes to customer support.  Knowing clearly what release a customer is using will make it a lot easier to reproduce any errors.

Quality Documentation

We all know that documentation is important, but quality is preferred over quantity.  Great documentation is made when you step away and can put yourself into the shoes of your users.  What questions are they going to ask?  What is going to be hardest for them to do?  Do you have any uncommon features?

We should include the obvious instructions on how to install both with the package manager and manually.

We should have special instructions on how to test it, how to get at the example code, and where the demo pages are located at.

I highly suggest using Github for your repository so that you get Issues and a Wiki with your project.  You can put the most basic documentation in your README.md and more details about architecture, types of named exceptions, API version handling, and everything else in the Wiki.

Optional Features (not exactly must-haves but are a good idea):

  • Continuous integration capable through online sources like Travis CI directly integrated into your Github README page.  It can give a great deal of confidence, but as long as you have clear instructions for a developer to run tests, this is just icing on the cake.
  • Providing your source via CDN (for a Javascript library).  Nice as it just takes one line to bring into an app, but for most bigger projects integrating via package manager is used more often.


There are a lot of under-appreciated features that go into a useful client API library, but it has to be designed with as much care and attention to detail as the API itself if you want it to be a business driver for your company.

If you are excited about creating a client API library for your API, but would like some help designing a client API library using these principles, please contact me on LinkedIn and let’s work together!


Subscribe to Front page feed