DEV Community: Blind Kai

Backend: Layered Architecture

Blind Kai — Sun, 23 Jan 2022 10:04:45 +0000

Motivation

Choosing the correct architecture for your backend application is an important decision because you will get the most of it in a long shot. This article is written to give Backend Developers an understanding of how to structure the code in order to make it properly incapsulated correspondingly to its purpose. Properly structured code that follows the same rules for each inner domain is easier to be read and maintain for you and other developers that would work with it. Better code you write at the start - less pain you get later when requirements will change.

Considering Layered Architecture

When developers work in the backend, they've mostly worked with data and business logic around that data. No matter if you're dealing with API or if it's CLI - you need to structure your code properly.

Layered Architecture is a great example of lightweight architecture which is not overwhelmed with redundant abstractions, contracts or boilerplate code.

In order to implement this architecture correctly, you just need to place your code in a place according to its properties and purpose.

General schema

For example, we need to design REST API architecture. If you're interested in reading more about REST API design, please check this link.
The general schema of layers is shown below:

As you can see, we have three layers, let's discuss them in detail:

Controller layer: Controllers themselves should only be responsible for work delegation. They should not contain any logic or direct data manipulation. The main purpose of a controller is to get the request, then pass it to the service that will process it and then return the response that is given from the service. See controllers like a manager for requests.
Service layer: Generally services contain information that is related to their domain. For example, if we have "Mail Service" we expect that sending/receiving emails happens there like in a real life. The same is fair for the codebase. Services (and their methods) handle the business logic which means that they are responsible for transforming data, performing additional actions (like asking the repository for additional data or another service for processing some logic for it). So if we need to send a mail, the service is responsible for getting the data as parameters, formatting them into the mail itself and sending it thru an external service or saving it thru the repository if it's an internal functionality.
Repository layer: If there is code that somehow works with the database here is the place for this code to live. No matter if we're fetching the data from the DB or saving/modifying objects, it's the place where SQL queries or ORM operations should be placed.

Detailed schema

Let's discuss a few workflows to have a better understanding of how things could work if we're building the REST API for some "Shop orders" domains.
Below you can see a few cases for writing domain code that follows the architecture:

Scenario A: User creates order

For example, we have a user that wants to create a new order. The request comes into the controller, the request is validated so we ensure that we're working with valid parameters.
Let's assume that the user also had discounts so we need to apply them in order to get the final price. For example, we have the service UserOrderService which has the method createOrder(user, order). Within this method, we calculate the discount that is available for the user (for example the user has a premium account or have a corporative discount so prices are lower). The calculations are the business logic so they live inside a service method calculateFinalPrice(order, discounts). After we are done with the logic, we could use UserOrderRepository with a method createOrder(order) which contains all fields like orderId, userId, creation date etc. Inside this method, we simply write our "INSERT" statement.

So we have a controller that passes the data into a service that process it and then the data is saved using the repository.

Scenario B: Confirm order, choose to ship and pay for the order

As you already see, here we have several things to work with. We have an order that should be confirmed, shipping options to be configured and money-related operations to be done.
So in practice, we get the request in our controller and pass it to the UserOrderService which handle logic that checks if the order can be confirmed with those parameters. After that, we're triggering services that have logic to work with external ShippingService and PaymentService. Those may contain some additional logic or utility methods that belong to them so we will need to implement some additional features for it. Finally, those services might trigger our repositories because we need to save that we need to pass the order to a shipping company and we know that the order is paid already.

Scenario C: User creates a comment below the bought product

The user got the order and want to give feedback (or post the comment on the product page). In this scenario, there is not much logic to work with the data (if comment moderation is manual. If it's done by AI it could have some logic in CommentService in method checkComment(comment)). If we have no logic there, we can simply pass the comment into CommentRepository which has a method called addComment(user, comment) and that's it. If no service is required you can simply trigger repository functionality from the controller.

Conclusion

Layered architecture is pretty simple and doesn't require developers to have big experience as well as it doesn't force developers to write too much boilerplate or deal with complicated abstractions and structures.
If you need to design MVP or if your project is not that big (yet) consider using layered architecture as a base architecture.

REST API Design

Blind Kai — Sun, 16 Jan 2022 18:41:12 +0000

Motivation

This article is written primarily for backend developers that are looking for some practical examples of "how-to" design their REST APIs so they would be strain forward for other developers as well as for API consumers.

The anatomy of the end-point path

HTTP method

Every endpoint belongs to the HTTP method. Those methods give developers and users a basic understanding of "what action" is performed on resources on that path. It's required to use the proper HTTP method for each endpoint. The details about each of the listed below methods can be found in RFC2616:

GET should be used if the endpoint returns information about the given resource ("list items", "get the item with ID=5", "get all subitems of the item with ID=5" and so on);
POST should be used if the endpoint creates a resource during request or should somehow change the state of the resources ("create new item", "perform authentication");
PUT is used when there is a need to completely replace a resource with an updated version. It's mostly used for update operations ("update item");
PATCH is similar to PUT but mostly is usable when you want to indicate, that the resource can be partly updated ("change user status to active", "grant user a permission/access");
DELETE as the name says, it indicates that the endpoint performs deletion of resource ("delete item", "delete all items");

Other HTTPS methods are less common to use and you probably will know if you need to use them.

Endpoint path

As we already know, the HTTP method is a verb, so to describe the endpoint path we need to use nouns (in other words "domain names").

For example to create a user we write:

POST /users          // GOOD
POST /create-user    // BAD

We've already specified POST as a method so we know, "it's going to create a user".

Another example to update user status:

PATCH /users/status     // GOOD
PATCH /users/set-status // BAD do not use verbs in paths
PUT   /users/status     // BAD use proper HTTP method

Most of the time you will face CRUD routes with some additional end-points to work with sub-entities:

GET    /users             // Get list of users
GET    /users/${userID}   // Get single user details
POST   /users             // Create a new user
PUT    /users/${userID}   // Update user
DELETE /users/${userID}   // Delete user

PATCH  /users/access      // Partly update user

GET    /users/${userID}/photos            // Get sub-entity
POST   /users/${userID}/photos            // Create sub-entity
DELETE /users/${userID}/photos/${photoID} // Delete sub-entity

Query parameters

Often you need to specify additional parameters for pagination or some kind of filtering that is provided by your server.

Pagination

If you're not using pagination on end-points that return lists of items, you probably should, because the growth of the database request would last a long time and suddenly block your server or database from running. The user also won't be happy to wait 15 seconds for items he doesn't want to see in numbers.

Example of query string with pagination:

GET /users?page=1&pageSize=25    // "Classic" pagination
GET /users?fromId=1232142        // Cursor pagination

Filtering

In case you need to specify some additional search parameters or return only specific entity fields you will also add them into query string and parse on the server-side:

GET /users?search=John      // Search for user with name John
GET /users?status=active,banned&age=18-21,22-27,40-49 // Return only active or banned users within the specified age groups. If you want to specify few filters you separate them by ","
GET /users?online=2021-12-01,2022-01-01 // Fetch users that were online in range of dates

Sorting

Users usually want to see "recent" items or updates, but sometimes they want to apply other sorting options:

GET /users?sort=last_online         // Sort by last online ASC
GET /users?sort=last_online,status  // Sort by 2 fields
GET /users?sort=name&desc=true      // Sort by name in descending order
GET /users?sort=+name,-status       // Multisort with specifying "+"/"-" as ASC/DESC

Response HTTP status codes

Depending on the result of the request the server should return a proper status code to indicate if the request was successfully finished or there were errors and it can't be finished.

It's also a good practice to use the defined set of codes for all end-points and provide additional messages within a response or in the documentation.

Those status codes are described at RFC 2616, RFC 4918, RFC 6585 and others.

Most of the time, you would be using those status codes:

2xx

200 OK - Simply means that the request was successfully performed and resource is available in response.
201 Created - Mostly used in POST requests as an indication that resource was successfully created and stored in the server.
204 No Content - Mostly used in DELETE requests to indicate that resource doesn't exist anymore.

4xx:

400 Bad Request - the request doesn't satisfy validation rules and the server denies processing it. Addition details about errors can be specified in the response body.
401 Unautorized - user is not authorized to use this end-point. Most of the time this is a status code to use if the user session is timed out or access token/session token was not provided in the Authorization header or within a cookie.
403 Forbidden - if it's a response to a sing-in end-point request it simply means that "there is no user with such username & password combination" or that user has no right to perform the request.
404 Not Found - the resource doesn't exist or there is no end-point on this address. The additional message about the error should be provided in the response body.
409 Conflict - mostly used when performing the request is impossible due to a constraint on the server (for example user with the specified nickname already exists) or if the given entity was already modified before the user sent a request.
422 Unprocessable Entity - means that the request schema is correct and it passes validation rules, but the server can't process the request or work with that query.
429 Too Many Requests - simply means that the user sent too many requests to the server (for example if the user tries to log in too many times in 1 minute).

5xx

500 Internal Server Error - your server should have a handler for unexpected errors and send a response to the user if there is something wrong before shutting the server down.

Conclusions

It's important to use things as they were designed to be used and to provide an interface that would be intuitive and easy to work with.
Also, don't forget to document your APIs using popular instruments like Swagger. It's helpful when you want to provide some explanations over "what does this status code mean" or "how to use filters in this end-point".
You will get some experience only by doing things. With all the basic rules you should be fine until you will come to some specific cases.

Using v-model with objects in Vue3

Blind Kai — Tue, 30 Nov 2021 20:42:24 +0000

Motivation

When I was using Vue2 along with vue-class-component and vue-property-decorator it was easy to synchronize v-models between components simply using @ModelSync(). When Vue 3 came out with its Composition API another way was needed to achieve the same result as if Class Component was used.

Implementation

If you're already familiar with the capabilities of Composition API, then simply use computed within setup to update the modelValue whenever it changes.

1) In child component define a model property with the default value

import { defineComponent } from 'vue';

<script>
export default defineComponent({
  name: 'FancyComponent',
  props: {
    modelValue: {           // Declare the property
      type: Object,
      default: () => ({}),  // Do not forget about default value
    },
  }
});
</script>

2) In setup() define a computed property and expose it:

<template>
  <div>
    <input v-model="theModel.foo" />  <!-- Usage of model -->
  </div>
</template>

<script>
import { defineComponent, computed } from 'vue';

export default defineComponent({
  name: 'FancyComponent',
  emits: ['update:modelValue'], // The component emits an event
  props: {
    modelValue: {
      type: Object,
      default: () => ({}),
    },
  },
  setup(props, { emit }) {
    const theModel = computed({  // Use computed to wrap the object
      get: () => props.modelValue,
      set: (value) => emit('update:modelValue', value),
    });

    return { theModel };
  }
});
</script>

3) In parent component use v-model directive:

<template>
  <FancyComponent v-model="someObject" />
</template>

TypeScript

In the case of using TypeScript, there is one minor addition to the code above. PropType<T> is used it order to annotate the model type.

<script>
import { defineComponent, computed, PropType } from 'vue';

interface OurModelType {
  foo: string;
}

export default defineComponent({
  name: 'FancyComponent',
  emits: ['update:modelValue'],
  props: {
    modelValue: {
      type: Object as PropType<OurModelType>, // Type Annotation
      default: () => ({}),
    },
  },
  setup(props, { emit }) {
    const theModel = computed({
      get: () => props.modelValue,
      set: (value) => emit('update:modelValue', value),
    });

    return { theModel };
  }
});
</script>

And it's all you need to know to pass reactive objects into your custom components as v-model.

Managing API layers in Vue.js with TypeScript

Blind Kai — Sat, 17 Jul 2021 09:32:42 +0000

Motivation

Almost every Single-Page Application at some point needs to get some data from the backend. Sometimes there are several sources of data like REST APIs, Web Sockets etc. It's important to manage the API layer in the right way to make it simple and easy to use in any place of your application no matter if it's store, component or another type of source file.

TLDR

If you already have some experience in development and want to check the solution here is the FancyUserCard example. If some things would be hard to understand feel free to check the detailed step-by-step path.

Bad

Performing API calls in the component is bad because:

You make your components large and filled with logic that has nothing to do with the component itself which violates SRP;
Same API methods could be used in different components which causes code duplication and violates DRY;
You are importing dependencies globally and it violates the DI principle;
Whenever API changes, you need to manually change every method that is needed to be modified.

Good

To make things work better we need to slightly change our code and move all the API calls into a separate place.

users.api.ts

In this case we:

Have one single AxiosInstance that is configured to work with /users API branch and our code becomes modular;
Have all methods located in one place so it's easier to make changes and to reuse them in different components without duplicating code;
Handle the successful request as well as request failure and make us able to work with both error and data object depending on request status;
Provide a standardized response return type for each method so we can work with them in one way.

FancyUserCard.vue

And in our component:

We are not dealing with the HTTP layer at all so our component is only responsible for rendering data that comes from the API layer;
Methods return both errors and data so we can notify your user if something went wrong or simply use data that was returned by a method.

Advanced

Some final changes:

The API call method was moved to reduce code duplication and all the methods are called using this private method.

Some other ideas

The approach shown above is enough to handle standard API layer workflow. If you want to make it even more flexible you could think about implementing some ideas below:

Creating abstraction over HTTP layerAbout the idea:

In the example, you can see that now we have an interface for our HttpClient so we could have as many implementations as we need. It works if we have different HTTP clients like axios, fetch, ky and if we will need to migrate from one to another we would simply need to rewrite our HttpClient implementation in one place and it will be applied automatically in any place where we use our service;

Create a factoryAbout the idea:

If you have few different data sources you could use some sort of factory to create the instance with needed implementation without an explicit class declaration. In this case, you just need to provide a contract interface and then implement each API method as you want.

About the problem

As you already know, dealing with API calls in your components is harmful because whenever the changes come you have plenty of work to do to maintain your code in the working state. Also, it can be pretty challenging to test components and API because they are directly and deeply coupled. We want to avoid those things while writing code so let's get through the example.

Example

This is the code for the initial example of an API call. For simplicity let's omit other code and keep attention only on the method itself.



axios
  .get<User>(`https://api.fancy-host.com/v1/users/${this.userId}`)
  .then((response) => {
    this.user = response.data;
  })
  .catch((error) => {
    console.error(error);
  });

As you can already see, we're accessing the component data() directly and use global axios which forces us to type more code for setting the request configuration.

TODO list

Migrate the code to a separate method;
Move from then syntax to async/await;
Setup axios instance;
Manage methods return type;
Incapsulate the method in Class.

Refactoring

1. Migrate the code to a separate method

To start with, lest move our code to the separate file and simply export a function that accepts userId as input parameter and return user object if the call was successful:



export function getUser(userId: number) {
  axios
  .get<User>(`https://api.fancy-host.com/v1/users/${userId}`)
  .then((response) => {
    return response.data;
  })
  .catch((error) => {
    console.error(error);
  });
}

Already an improvement! Now we can import this function whenever we need to get User. We just need to specify the userId and we're ready to go.

2. Move from `then` syntax to `async`/`await`

In real world there are often situations when you need to make sequential calls. For example, when you fetch user you probably want to get information about posts or comments related to user, right? Sometimes you want to perform requests in parallel and it can be really tricky if we're talking about .then implementation. So why won't we make it better?



export async function getUser(userId: number): Promise<User | undefined> {
  try {
    const { data } = await axios.get<User>(`https://api.fancy-host.com/v1/users/${userId}`);
    return data;
  } catch (error) {
    console.error(error);
  }
}

As you can see, now we are providing additional typings and using await to stop our code from running until the API call finishes. remember that you're able to use await only inside the async function.

3. Setup `axios` instance;

Okay, so now the longest line is the one with the end-point URL. Your server host is probably not going to change often and it's better to keep your API branch set up in one place so let's get into:



const axiosInstance = axios.create({
  baseURL: "https://api.fancy-host.com/v1/users"
});

export async function getUser(userId: number): Promise<User | undefined> {
  try {
    const { data } = await axiosInstance.get<User>(`/users/${userId}`);
    return data;
  } catch (error) {
    console.error(error);
  }
}

Much better. Now if your /users API branch will change, you could simply rewrite it in the instance configuration and it will be applied to every call made using this AxiosInstance. Also, now you could use something called Interceptors which allows you to make some additional changes to requests/responses or perform logic when a request is made or response is back. Check out the link to get more details!

4. Manage methods return type

What if I will say to you that your user doesn't understand if (and why) something went wrong .. until! Until you provide some information about "what went wrong". UX is really important to keep your user happy and make the workflow better at all. So how are we going to do that? Simply by returning both data and error from our API call. You could also return as many things as you need (if you need them, right?):



export type APIResponse = [null, User] | [Error];

export async function getUser(userId: number): Promise<APIResponse> {
  try {
    const { data } = await axiosInstance.get<User>(`/${userId}`);
    return [null, data];
  } catch (error) {
    console.error(error);
    return [error];
  }
}

And how it will look when we use it, for example in our created() callback:



async created() {
  const [error, user] = await getUser(this.selectedUser);

  if (error) notifyUserAboutError(error);
  else this.user = user;
}

So in this case, if any error happens, you would be able to react to this and perform some actions like pushing an error notification, or submit a bug report or any other logic you put in your notifyUserAboutError method. Elsewise, if everything went okay, you could simply put the user object into your Vue component and render fresh information.

Also, if you need to return additional information (for example status code to indicate if it is 400 Bad Request or 401 Unautorized in case of failed request or if you want to get some response headers if everything was okay), you could add an object in your method return:



export type Options = { headers?: Record<string, any>; code?: number };

export type APIResponse = [null, User, Options?] | [Error, Options?];

export async function getUser(userId: number): Promise<APIResponse> {
  try {
    const { data, headers } = await axiosInstance.get<User>(`/${userId}`);
    return [null, data, { headers }];
  } catch (error) {
    console.error(error);
    return [error, error.response?.status];
  }
}

And usage:



  async created() {
    const [error, user, options] = await getUser(this.selectedUser);

    if (error) {
      notifyUserAboutError(error);

      if (options?.code === 401) goToAuth();
      if (options?.code === 400) notifyBadRequest(error);
    } else {
      this.user = user;

      const customHeader = options?.headers?.customHeader;
    }
  }

As you can see, your requests become more and more powerful but at the same time, you can make your components free from that logic and work only with those details you need.

5. Incapsulate the method in `Class`

And now there is time for the final touch. Our code is already doing a great job but we can make it even better. For example, there are cases when we want to test how our components interact with other layers. At the same time, we don't want to perform real requests and it's enough to ensure that we make them correctly at all. To achieve this result we want to be able to mock our HTTP client. To make it possible, we want to "inject" a mocked instance into our module and it's hard to imagine a better way to do that than with Class and its constructor.



export class UserService {
  constructor(private httpClient: AxiosInstance) {}

  async getUser(userId: number): Promise<APIResponse> {
    try {
      const { data } = await this.httpClient.get<User>(`/${userId}`);
      return [null, data];
    } catch (error) {
      console.error(error);
      return [error];
    }
  }
}

And the usage:



const axiosInstance = axios.create({
  baseURL: "https://api.fancy-host.com/v1/users"
});

export const userService = new UserService(axiosInstance);

In this case, you don't expose your AxiosInstance and provide access only thru your service public API.

Conclusions

Hope that this article was useful for you. Do not hesitate to leave a comment if you have some other ideas or if there are any questions about the content of this post. I will update this post with detailed information about the problem, the solutions and the refactoring process soon.
Cheers!

DEV Community: Blind Kai

Backend: Layered Architecture

Motivation

Considering Layered Architecture

General schema

Detailed schema

Scenario A: User creates order

Scenario B: Confirm order, choose to ship and pay for the order

Scenario C: User creates a comment below the bought product

Conclusion

REST API Design

Motivation

The anatomy of the end-point path

HTTP method

Endpoint path

Query parameters

Pagination

Filtering

Sorting

Response HTTP status codes

2xx

4xx:

5xx

Conclusions

Using v-model with objects in Vue3

Motivation

Implementation

TypeScript

Managing API layers in Vue.js with TypeScript

Motivation

TLDR

Bad

Good

users.api.ts

FancyUserCard.vue

Advanced

Some other ideas

Creating abstraction over HTTP layerAbout the idea:

Create a factoryAbout the idea:

About the problem

Example

TODO list

Refactoring

1. Migrate the code to a separate method

2. Move from then syntax to async/await

3. Setup axios instance;

4. Manage methods return type

5. Incapsulate the method in Class

Conclusions

2. Move from `then` syntax to `async`/`await`

3. Setup `axios` instance;

5. Incapsulate the method in `Class`