Develpreneur: Become a Better Developer and Entrepreneur

One of the most substantial challenges in system development is the application programming interface. The result is (ideally) a stable and well-defined interface for your system. That can be a struggle when your solution is not exactly stable nor well-defined. Nevertheless, that does not excuse you from ignoring the API until implementation. It needs to be addressed in the architecture from the start. A Basic Application Programming Interface When you know an API will be required, you can always take the simple route. Review the core data items, and features then create a pass-through of sorts. While this is not the most elegant solution (and not recommended), it is a start. When you start with this approach, try to keep the endpoints minimal, and you can grow those properly as the system evolves and matures. Set The Stage The best map for your API is going to come from the user stories and requirements. There are two primary reasons for an API. You are either providing integration for external systems or an import/export feature. That boils down to a modest API that has a few ways to extract or send in data in the latter case. In the former case, you will be providing endpoints to match the user stories. Therefore, your API will either be driven by your data structures or your feature set. That is not to say you cannot do both. An API is almost always some combination of those two areas of focus. Stay Ahead Of The Needs We started by mentioning that you can build a solution and then provide an API, or you can design the API before implementation. You will find it far more challenging to "tack on" an API after implementation. There are often assumptions made within an application that will not be valid once you open its doors via an API.

When we talk about creating an architecture for the future, integrations should always be a part of the discussion. These include importing, exporting, and direct integrations via an API. It is limiting to assume that an application will always stand on its own. Even a solution that proves better than all others is served by providing a way for other application data to be brought in. Simple Integrations Importing and exporting data are the easiest ways to integrate with other systems. While there can be some challenging mappings, these often are little more than selecting the fields to work with and connecting in a one-to-one manner. Even the most complicated import or export processes can off-load some of the most onerous work to a manual process. This approach is not the most desirable, but it is an option. A Common Language When your architecture provides hooks for imports and exports you are making those mappings easier. These in and out methods can combine to become a form of language your system speaks. When someone wants to bring data into your system, they need to translate that data into your language or format. Therefore, these features off-load work the implementation team would have to do to more directly integrate with other systems. Better yet, a well-defined export and import process puts the onus on others to work with your system instead of creating customizations for other systems. Full Integration Importing and exporting data are ways to integrate with other systems. However, those are limited integrations. It is difficult (if not impossible) to do a realtime integration via these methods. That is where an API can save the day. The application programming interface is rarely easy and requires coding. Nevertheless, it provides far more lee-way and control in system integrations. There are some problems that can only be solved by creating this level of integration.

System logs and logging is one of the least sexy things in software development. Nevertheless, they are highly valuable. The ultimate challenge in a logging architecture is balancing information with performance. That is why you want to tackle this during the architecture process. It is time-consuming when left until implementation or beyond. Where To Keep System Logs The architecture part of logging often boils down to location. There are facets of storage like archiving, rollover, and format. However, these are often driven by storage decisions. These include options like a file or database solution, a single file or one per system, and accessibility considerations. Any of these options can be valid. On the other hand, they may not be the best choice for your specific system. Keep in mind that a single large file may be easy to design, but it will be challenging to use for debugging. Security Is Important Log files are information-rich by design. That means they can be useful to hackers that are trying to find access credentials, loopholes, or even reverse engineer your system. You may need to partition out information to different file locations or limit the data logged. There are also compliance issues like HIPPA or PCI to guide you in what should not be sent out to a log. Performance Options Most modern logging libraries include settings to allow you to set the amount of data logged form none to profuse. These features are excellent. However, you want to do what you can to lead the implementation team to follow a consistent approach. While this can be covered in coding standards, you can also create an architecture that leads them in the right direction. System logs are a feature of an application that often are ignored until something goes wrong. Thus, it is not uncommon for maintainers to complain about poor or limited logging in a system. When you keep these features in mind while architecting the solution, it is more likely you will avoid this weakness.

While the GUI is used for most of our user interaction, there are other methods to consider as well. The areas of focus in this episode will be messages and notifications. Much like other details of our solution, these need to be architected. Our goal is to provide a consistent experience and easy use of these tools for implementation. Messages Of the two items in this episode, these are easier to design. The architecture will often be a text file with message text values. Alternatively, they can reside in a database. While both options are viable, the database solution tends to be easier to maintain and extend. You will also have to determine whether the messaging approach is a one size fits all solution. This approach may not be correct if you have multi-lingual support for your application. For example, a Spanish speaking user should not see an English message and vice versa. Notifications This means of communication has the same general challenges that we saw with messages. However, notifications tend to go outside of the system. Thus, they have obstacles related to that integration outside of areas we control. These are architectural decisions that should be made early on. It is harder to tack on such a feature down the road. For example, notifications are often sent that require a response. For messages, it is simple to grab a response in a pop-up window. However, what happens when we want a response to an email or text? There are several ways to design your solution to support these responses (email reader, API functions, etc.). That provides flexibility. On the other hand, most of these solutions require a certain set of features to be architected and adequately designed. You have to consider security and validation. What happens if your email goes to the wrong person, and then you get an incorrect response? Timing Issues Another issue that you can run into with notifications is timing. Multi-factor authentication often hits this obstacle by expiring secondary auth codes (texted to you or sent via email). These may expire in a matter of minutes. The assumption (correctly) is that the longer those notification specific response links or values stay around, the higher the security risk. While many actions in a system will be serial (for typical systems), the messages and notifications features will rarely be so simple.

Hackers are everywhere. Thus, security and authentication are essential pieces of software architecture. There are so many common features of application security available it may seem like no real thought is needed. You can just grab the essential features "off the shelf." Nevertheless, there is much to nail down in architecting the best solution for your specific application. Start With Security And Authentication There are applications that are created with security and authentication left as a finishing touch. This approach is often taken to simplify testing and validation during the implementation phase. However, these are features that should be built into every piece of the application. When you fail to do so, it is too easy to miss details and leaves holes that can be exploited. Thorough Testing One of the best arguments for security from the start is the value of testing. When you force all of your tests to be run in a secure environment it makes them more valid. You are far more likely to find situations that only occur in a secure application. Be they bugs, gaps, or restrictive permissions. These are not only important for a secure system, but they can also be difficult bugs to find in the wild. More to the point, your QA scripts should include a validation of every secured item in the system. When they do not, testing is not complete. Security Throughout A secure system is much more complicated than an open one. There are decisions to make in almost every area that impact security. When you put them off, they may need to be altered. For example, we may have data that is only accessible by a specific user (or users). We need to make sure that every possible option for accessing that data is secured. This includes an authorization requirement on every tier and for every access point. Failing to incorporate security into the system from the start can lead to costly (and risky) changes far down the SDLC process. The effort is worth it.

Systems and solutions will grow if they are successful. Therefore, it is essential for us to consider whether this will be handled by scaling up or scaling out. There are many ways that a solution will need to grow. There can be limitations based on processing, storage, network, or other areas. Each of these can grow in the same way or you can mix-and-max your way through these issues. No matter the approach, it needs to be thought through as part of the architecture. Scaling Up The first way to scale a system is up. This essentially keeps everything in place while making it stronger or more powerful. In the computer world, this can be a bigger storage drive, more memory, or a faster processor. All of these options help a system respond faster and support more users. Of course, there is a limit to this growth. While easier to build, an architecture that is designed to scale up will hit a ceiling at some point. Scaling Out Scaling out involves replicating systems and using those new ones to provide a service. You roughly split up the total user base into a bunch of smaller bases that can be served by a smaller solution. This allows for almost infinite scalability. The downside is that you have obstacles to overcome to split out the work and make it seamless. Your users will not often make it easy to splinter them out into groups. On the other hand, some applications are perfect for scaling out. This situation is exactly why microservices have their niche. Learning More There is a lot more that factors into which way an application should scale. Rather than tackle those here, check an article like this one. Your solution is unique and needs a similar approach to how it scales. Luckily, growth is a good challenge to face.

Nearly every solution includes some manner of administrative tools. These tools range from scripts and manual process steps to full graphical interfaces and wizards. No matter the form these take, they must be considered as part of architecting a solution. Their very nature is for it to work hand in glove with the architecture and design to manipulate data as needed. Low-End Administrative Tools The simplest form of tools are scripts and similar utilities that are primarily manual. These are often built around the architecture and implementation after the fact. While that is acceptable, it is not ideal. There are many times that I have seen these tools pushed off until after production deployments only to find that the proper hooks were not built into the system. We often find a need to design things like back-doors to allow for proper administrative tools. When those are not architected from the start, then they can be difficult or impossible to utilize. Architecting For The Long Run The best place to set up a system with a good (and productive) administrative user experience is the architecture itself. I used the "shop as a customer" feature that many e-commerce tools have adopted. This feature is highly valuable when supporting an e-commerce environment. If we back up a step, then consider what the most crucial question is to answer during a support call. That is "what were you doing before it broke" or something along those lines. When we provide administrative tools that allow the support staff to mimic users, then they have better chances of reproducing the precise bug. That makes fixes easier to determine. User mimicry can even be a tool that helps push bugs up the call center tier to ever more technical levels of support. Make Your Life Easier A good architecture will allow access to the data where needed. You can always secure these points to protect your back doors. However, the door must exist first. When you fail to plan for support issues is can be costly. Unfortunately, this cost is not one you will see right away. Instead, it will be a drag on your maintenance and support team for years to come.

No matter what we build, there is always a foundation of some sort. In software, the core component architecture provides us that foundation. These are the models or objects that provide the framework for all of the other functions. When you design these core pieces of your solution, it is essential to get them right. When you fail to do this, you will have problems throughout the system. It Starts With The Problem Once again, we refer back to the primary problem or problems we are solving. The solution will require certain pieces of data and functionality that will impact the entire solution. These items may include security, standard functions, critical data elements, and more. The core component architecture is not an MVP for the system. However, it is the collection of items that have to exist and interact to solve the problem. These are the common denominator aspects of your solution. Thus, the decisions made here will percolate throughout your application. Defining The Core Component Architecture The foundation we are building will become apparent as the pieces of architecture are put into place. There will be functions, features, and data that show up time and time again as you work through the system. That is the nature of the core components. They are the pieces that are "touched" the most as you move through the various processes. Therefore, improvements (or flaws) in these areas will have the most significant impact overall. Measure Twice There is an old saw (pun not intended) about measuring twice and cutting once. This is important to keep in mind as you work on the core component architecture. These may not be the flashiest parts of your application. However, they are the ones that are most important to get right.

The modern world is full of options to connect your app to the Internet. Nevertheless, there are cases where you will have a sometimes connected application. This situation impacts architecture and needs to be understood before starting. "Sometimes" is a challenging situation to handle with your architecture. Thus, it is easier to architect a solution that is always connected. Better yet, one that is completely stand-alone. Danger Zones First, it may help to highlight some of the areas and types of applications that will fall under this umbrella. Certain building types are often problematic for wireless connections. These include anything that is mostly concrete, including (in many cases) government buildings, schools, military locations, hospitals, and prisons. Applications that are going to be used by those that travel can also fall into this category. Some examples are sales applications, insurance or real estate assessors, physical therapists, and athletes. When in doubt, take a good look at your target user base. Possible Solutions For A Sometimes Connected Application The good news is that this is not a new challenge. There are a lot of people that have gone before you that have found ways to address this. Also, the solution is generally simple to understand. It is just the number of situations that need a review. There is almost a confusing number of options available. The solution is to provide access to the data when needed. This option may seem overly simple. However, it is essential to your approach. Some applications are ok with being useless in a disconnected state. In those cases, you can act like the user is always connected and close the app when they are not. Once you eliminate the "you can't use this unless connected" option, it gets trickier. You have two main options. You can cache data or reduce functionality. Also, these are not mutually exclusive, so you have this choice to decide for almost every piece of functionality. The Cache Problem While caching data seems like a simple solution, it is not. There will come a time when you need to merge data back into the system. Ask anyone that has had to merge data as to how challenging that can be. In particular, when both sides of the merge may have changes the same data. There are usually rules to follow in those cases. However, getting the comparisons and remediation steps implemented can be grueling. The process also tends to be full of outliers and other special circumstances. In these times, remember that slow and steady wins the race.

Architecture design can start at the back-end or the front-end. In either case, you will end up architecting the user experience at some point. The architecture will come out of the user interface and the controls you use. It will be joined with the way you architect the visual portions of the application. The result is more than look-and-feel and goes beyond designing some visual styles. Setting The Tone There is a tone or voice an application has that is beyond just the look-and-feel. It probably falls into the "feel" portion of that facet. However, I think this an area we rarely consider. We tend to focus on color schemes and icons without spending enough time on content. The words we use, the grammar applied (or not), and how we address the user all fall into a tone for the user experience. When we architect the user experience, there are going to be results that include a focus on fewer (or more) clicks, navigational approaches (top, middle, side), and other thematic UI decisions. The architecture will often include a decision on libraries, supported platforms, and other core UI components. Directing the Flow User experience architecting includes working with also and altering user habits. For example, we are taught in the West that users tend to visually move left to right and top to bottom on a page. While we do not want to fight against that habit, we can work with it to improve the user experience. These changes can include colors, fonts, and common areas for specific functions. Architecting the user experience includes setting up these commonalities. We will do things like creating a standard template for forms that has a save button at the bottom, or maybe we always save data when the user exits a screen. We will display the error and warning messages in a consistent location with standard colors. These choices and more will be a part of this portion of our architectural journey. Provide Building Blocks An architect does not need to implement a solution. However, they can mock-up and layout a series of wireframes, scaffolding, or other guides. These help the implementation team follow the plan. A good architecture will make it easy for the implementors to follow the plan and maybe help them be more productive in doing so. If you want to learn more you can check out this article: Incorporating User Experience Into Your Solution From The Start or go to a great UX source: https://www.smashingmagazine.com/2010/10/what-is-user-experience-design-overview-tools-and-resources/