The Importance Of Choosing the Right Architecture Pattern

The Importance Of Choosing the Right Architecture Pattern

What are software architecture patterns?

 

When writing software, engineers encounter many of the same problems over and over again. Because of this, design patterns have been defined that give engineers a reusable way to solve these commonly occurring problems. At a higher level, software architecture patterns exist that give engineers a way to accomplish the same thing structurally for the entire project. There are many different types of applications and each application might benefit from a different architecture pattern.

One of the most common patterns and one we use frequently here at Shockoe is the layered pattern. The idea behind the layered pattern is that the code should be split into layers and each layer should have a distinct responsibility, while also being able to provide some service to a higher layer. So, for example, you might have a presentation layer that responds to user interaction with a screen and then passes data to a higher layer (frequently an application layer) and so on and so on until it reaches the highest level that has been defined in the architecture.

 

Why does it matter?

 

One question that could be asked is – Why is it important to choose the correct app architecture? This can be answered from two perspectives; that of the engineer and that of the client. We’ll start by answering it from the perspective of the engineer.

Most engineers are familiar with common architecture patterns. This means that when a new engineer joins a project or a team of engineers takes on an existing project, they are better able to navigate the project structure and can begin work much more quickly and with more confidence that new features can be added without any issues. Additionally, as new features are added it is very clear which part of the architecture needs to be modified and teams can work together on different layers of the architecture. All of this leads to more stable applications with fewer bugs and better performance overall.

From the perspective of a client, there are many reasons why choosing the right application architecture is important. Clients need to be able to be sure that the engineering team that they choose to build their application has their best interests in mind, both in terms of quality and efficiency. Software architecture patterns allow for higher levels of quality to be achieved while still maintaining efficiency. There is also no one-size-fits-all architecture that can be applied to every project. For example, a highly complex enterprise level application would demand a more sophisticated architecture pattern than a simple proof of concept or minimum viable product application. Also, when a project is released and then additional features are required the client can be sure that this process will be as painless as possible because well-architected software can be modified much easier than software with poor architecture.

 

Conclusion

 

Building software requires planning. Without a plan, even a trivial project can quickly turn into an unmanageable mess. This introduces what is referred to as technical debt into the project. As technical debt increases, costs to the client increase and overall performance and quality of the application decreases. As I mentioned before there is no one-size-fits-all approach to software architecture and at Shockoe, we pride ourselves on being experts when it comes to choosing the right application architecture for each project and making sure that we deliver the highest quality applications to our clients in the most efficient way possible.

 

Stephen Shaw

Stephen Shaw

Software Developer

Stephen Shaw is a mobile software engineer, primarily focused on building native iOS applications. Born and raised in Richmond, VA, he enjoys spending time hiking by the river, trying new restaurants, and exploring everything the city has to offer with his fiancé, Rachael. Passionate about learning something new as much as possible, he is always seeking out ways to acquire knowledge.

How to Document an Existing API Using Swagger

How to Document an Existing API Using Swagger

A few months ago, I jumped into an exciting project with my teammates at Shockoe. My expertise was needed for testing and debugging, which led me to begin working with the middleware API. In this particular case, the project presented new challenges, APIs that had already been set up by a client and the fact that this was an ongoing project, which meant that it was still changing and being updated regularly.

Adding features to the project required new resources and endpoints. Updating how error messages were handled required updating API responses and, after a certain point, enough changes had been made that the documentation had to be remade.

I came across two popular resources for documenting APIs: Swagger and RAML.

RAML takes a top-down approach to defining APIs, which means that you first define what your methods will be and then how they will work. By using a methodology that involves defining the system and providing the details later, this works well while developing an API since it goes alongside the developing mindset.

On the other hand, Swagger uses a bottom-up approach, defining each method one at a time. In my case, I decided to use Swagger because this methodology works better when documenting an already existing API. Swagger basically allows you to work through each API call and document as you go.

Swagger uses JSON objects to describe its API request and responses. For example, an API with a pets endpoint for a GET request could look like the example below, with a separate items object defined later in the document to increase readability.

{
  "/pets": {
    "get": {
      "description": "Returns all pets from the system that the user has access to",
      "produces": [
        "application/json"
      ],
      "responses": {
        "200": {
          "description": "A list of pets.",
          "schema": {
            "type": "array",
            "items": {
              "$ref": "#/definitions/pet"
            }
          }
        }
      }
    }
  }
}

Since I had already been using Postman to test each call, I had a quick way to go through each call, document the request and response, and move on to the next step.  Because the API only returned JSON the similarity between formatting for the response and the swagger response documentation led me to create a simple conversion program. This allowed me to easily input the response from an API call and output a properly formatted swagger documentation for it.

function convertToSwagger(item){
  var string = '';
  if(item === null){
    string += '{\n'+'"type": "string"\n'+'},';
  } else {
    switch(typeof item){
      case "string":
        string += '{\n'+'"type": "' + typeof item +'",';
        if(item.length > 150){
          item = item.substring(0,150);
        }
        if(item.includes('"')){
          string = string.slice(0,-1);
          string += '\n'+'},';
        } else {
          string += '\n';
          string += response ? '"example": "' : '"default": "'
          string += item + '"\n'+'},';
        }
        break;
      case "number":
        if(Number.isInteger(item)){
          string += '{\n'+'"type": "' + 'integer' +'",';
        } else {
          string += '{\n'+'"type": "' + 'number' +'",';
          string += '\n'+'"format":"float",';
        }
          string += '\n';
          string += response ? '"example": ' : '"default": '
          string += item + '\n'+'},';
        break;
      case "boolean":
        string += '{\n'+'"type": "' + 'boolean' +'"\n'+'},';
        break;
      case "object":
        if(Array.isArray(item)){
          string += '{\n'+'"type": "' + 'array' +'",';
          string += '\n'+'"items": ' + convertToSwagger(item[0]).slice(0,-2) + '\n'+'},';
        } else {
          string += '{\n'+'"type": "' + 'object' +'",';
          string += '\n'+'"properties": ' + '{\n' + createProperties(item) + '\n'+'}\n'+'},';
        }
        break;
      default:
        // do nothing
    }
  }
  return string+"\n";
}

At this point the process became simple, look up the API request, document the new path in Swagger (which can be made easier by copying an existing path and changing the different fields), make a request to get a sample response, put the response in the converter and copy it over to the swagger file. From here, I was able to quickly finish documenting the API and set up a process to easily keep it updated or document another finished API.

Documenting a project can seem daunting when you need to do it all at once, but it is still a very important part of the process. In the end, I found Swagger to be a great API document that was easy to use for my project needs. I was able to quickly pick it up and get started. Adding each method was simple to do after the first one and it helped give an overview of all the available methods while showing example requests and responses along the way. I hope this helps you when you find yourself documenting existing APIs, leave us a comment if you have any questions or insight on how to use Swagger.

Editor: Interested in learning how our developers debug applications? You can read more from our last week’s blog. For our blog on API Description Language for the Enterprise click here.

Want to stay connected on all things mobile?

 

Sign up for the Shockoe newsletter and we'll keep you updated with the latest blogs, podcasts, and events focused on emerging mobile trends.