# Guidelines

# General recommendations

  • Always keep in mind Ubiquitous Language (opens new window) when naming something.
  • Use linters, vulnerability checkers and static analyzers.
  • Strive to improve the quality of the code while working with it. If a quick fix degrades the quality of your code, plan a refactoring.
  • Remember, your code should be understandable both to you and to your colleagues.

Prefer composition instead of inheritance (opens new window) .

  • Beware of creating Reusable components from the very beginning. An extra layer of abstraction will complicate its use. *. When you get some data from external sources (e.g. database, http call etc.) do typechecking right at the beginning. Ideally it should be done inside the adapter. So when data is coming out of adapter, it should already be type checked.
  • Take care of exceptions. On the low level we should catch them and rethrow some specific exception, at the same time logging message with the error.
  • When you get some data from external sources (e.g. database, http call etc.) do typechecking right at the beginning. Ideally it should be done inside the adapter. So when data is coming out of adapter, it should already be type checked.
  • Take care of exceptions. On the low level we should catch them and rethrow some specific exception, at the same time logging message with the error.

# Comments in code

  • Write comments in English.
  • Add the comments with the information that is not obvious when reading the code,e.g. describe side effects.
  • High-level comments on a class / module should not describe implementation details. If the class has a separate interface, write comments in the interface.
  • Low-level comments describe the code and should answer the questions: "What?" and "Why?" and not "How?".
  • If a bug fix requires writing complex code, also include the issue number from JIRA in the comment.
  • Update comments at the same time as the code, do not duplicate.

# Refactoring

  • Plan refactoring in Avion.
  • Make sure tests cover the code you are going to change.
  • Make the plan of what you are going to change and keep to it.

# GIT recommendations

  • If you did some refactoring which is not related to your task, separate refactoring changes from actual changes required for your task. So it is better to create MR1 -> develop|master with actual changes and MR2 -> MR1 with refactoring.
  • Make and push commits regularly.
  • Commits to an upstream must-have Jira ID. E.g., PROJ-5222 your message If you're working in a branch and later intends to use squash commits, you can omit to add Jira ID.
  • Use Present Simple tense for commit messages. E.g., PROJ-5522 add README.md.

# Release versioning

We follow SemVer 2.0 (opens new window) conventions.

+------- MAJOR version when you make incompatible API changes,
| +----- MINOR version when you add functionality in a backwards compatible manner, and
| | +--- PATCH version when you make backwards compatible bug fixes.
| | |
x.x.x

# API

# REST API

# Documentation

We use swagger/openapi format.

# Versioning

Add the version number to the prefix:

GET /api/v1/
GET /api/v2/

Use only major versions. It is unacceptable to rename methods or parameters within the same version.

If a parameter needs to be changed, the version number must be raised and there should be backward compatibility with the previous version of the API.

# Endpoints naming

Collection names in plural:

GET /campaigns
GET /campaigns/123

Use nesting to show how the objects relate:

GET /campaigns/123/webhook/1

# Endpoints methods

Endpoint names should contain only nouns. The action is defined by the http-methods:

HEAD /offers/123    # returns only HTTP headers, no body
GET /offers/123     # requesting  an offer with ID 123
DELETE /offers/123  # removing an offer
POST /offers        # creating a new offer
PUT /offers/123     # editing an offer with ID 123
PATCH /offers/123   # editing of only certain parameters of the offer

If specific actions are performed on the object, verbs can be added:

PUT /offers/123/disable

# Statuses

We use standard HTTP codes (opens new window). Most used:

200 - everything is OK
202 - action accepted but will be performed later
400 - invalid parameters were passed in the request
401 - authorization required
402 - the paid period is over or this action is not available in the current edition
403 - with the current authorization, access to the object is denied
404 - endpoint or object does not exist
405 - invalid endpoint method is sent
406 - unacceptable request, validation error, incorrect data sent
429 - request limit exceeded

# Errors

Send the error text in the response:

{
    "error" => "This campaign is already started"
}

Extended variant:

{
    "error" => "This campaign is already started",
    "code" => "campaign_started",
    "documentation_url": "https://developer.github.com/v3"
}

# Parameters:

  • sort - sorting (asc by default):

    GET /offers?sort=name

    GET /offers?sort=name:asc GET /offers?sort=name:desc

    GET /offers?sort=name:asc,country:desc

  • offset and limit for pagination:

    GET /offers?offset=10&limit=10

  • filter for filtration:

    GET /offers?filter

Dates in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.

# Limiting requests

If the API has a request limit, the following headers must be sent in the response:

  • X-RateLimit-Limit - the rate (number) of the limit
  • X-RateLimit-Remaining - how much is left until the limit is reached (number)
  • X-RateLimit-Reset - how many seconds (opens new window) are left before the restrictions are reset

# Logging

  • A log of API requests and responses must be kept. All personal data and passwords must be filtered.

# Monitoring

# Health-checks

  • Describe entrypoint to check the state of the application. Read about livelinessProbe (opens new window) .
  • If the application needs time to warm up before it can serve traffic, write readinessProbe (opens new window) .
  • General rule is that liveliness and readiness probes should be always present and application should have corresponding http routes to serve this requests.

# Business metrics

Read about uploading metrics to Prometheus (opens new window).

Make sure that the metrics are not accessible from the outside and that access to them through ingress is

denied.

# Books

  1. A Philosophy of Software Design (opens new window)
Last Updated: 11/22/2021, 9:23:22 AM