Skip to content

✅ Service Contracts

📘 Service Contracts – API-First Approach

🧾 What is a Service Contract?

A service contract is a formal agreement that defines how a service will behave:

  • What endpoints it exposes
  • What requests it accepts
  • What responses it returns
  • What status codes and formats it follows

It’s like a blueprint for how services talk to each other — clear, consistent, and agreed upon before building.

🚀 What is API-First Approach?

In an API-First approach:

You design the API contract first, before writing any code.

This means:

  • The API spec (OpenAPI/Swagger, Protobuf, GraphQL schema) is the source of truth.
  • Development teams can work in parallel — frontend, backend, QA — all rely on the same contract.
  • The contract acts like a mockable stub or scaffold early in the project.

🛠️ Tools Commonly Used

  • OpenAPI/Swagger – REST APIs
  • AsyncAPI – Asynchronous/message-driven systems
  • Protobuf – gRPC APIs
  • Postman / Stoplight – API design, testing
  • Pact – Contract testing (Consumer/Provider)

✅ Benefits of API-First Approach

Benefit Description
🤝 Better collaboration Frontend and backend can develop in parallel
🧪 Early testing Use mock servers to validate early
📚 Auto documentation Docs come from the API definition
✅ Validation & Safety Ensures contracts are followed and changes are tracked
🚧 Catch breaking changes Prevents accidental API breakage

🧠 Real-World Example

Let’s say you're building an Order Service.

With API-first:

  1. You first write the OpenAPI spec:
paths:
  /orders:
    post:
      summary: Create a new order
      requestBody:
        ...
      responses:
        201:
          description: Order created
  1. Frontend uses the spec to build UI.
  2. Backend uses the spec to generate controllers.
  3. QA uses the spec to mock and test early.

📘 OpenAPI / Swagger / Scalar — Simple Explanation

🌐 What is OpenAPI?

  • OpenAPI is a standard format (a specification) to describe REST APIs clearly and consistently.
  • It’s like a contract or blueprint that shows what API endpoints exist, what data they expect, and what they return.
  • Written in YAML or JSON format.
  • Helps tools generate documentation, client SDKs, and tests automatically.

🛠 What is Swagger?

  • Swagger is a set of tools built around OpenAPI.

  • It includes:

  • Swagger Editor — to write OpenAPI specs.

  • Swagger UI — to display API docs as a friendly webpage.
  • Swagger Codegen — to generate client/server code.
  • So, Swagger = tools to work with OpenAPI specs.

🔡 What is a Scalar?

  • In API schemas (like OpenAPI or GraphQL), a Scalar is a basic data type that holds a single value.

  • Examples of scalars:

  • String — text like "Hello"

  • Integer — whole numbers like 1, 42
  • Boolean — true or false
  • Float — decimal numbers like 3.14
  • Scalars are the building blocks of request/response data structures.

🧩 How they fit together:

Term What it means
OpenAPI The specification for describing REST APIs
Swagger The toolset to create, visualize, and use OpenAPI specs
Scalar Basic data types used inside API definitions

🔙 Backward Compatibility

What is Backward Compatibility?

Backward Compatibility means:

When you update a service or API, the new version still works with older clients or consumers without breaking them.

In other words, old clients can keep using the new service without errors.

Why is it important in Microservices?

  • Multiple services and apps may call your API.
  • You can’t force everyone to upgrade at once.
  • You want to release new features or fix bugs without stopping old clients.
  • Ensures smooth evolution of services over time.

How to maintain Backward Compatibility?

  • Add new fields but don’t remove existing ones.
  • Make changes additive, not breaking.
  • Avoid changing existing data types or request formats.
  • Support old API endpoints or versions (versioning).
  • Use default values for new fields.

Example:

If your API response used to return:

{
  "name": "John",
  "age": 30
}

You can add a new field like:

{
  "name": "John",
  "age": 30,
  "email": "john@example.com"  // new field added
}

Old clients ignoring email still work fine.

Summary

Backward Compatibility helps you improve your microservices without breaking existing users — a key part of good API design!

⚙️ Setting up Development Environment

1. Tools & IDEs

  • Visual Studio / Visual Studio Code — Popular IDEs for microservice development.
  • Postman / Insomnia — API testing tools.
  • Database Clients — e.g., SQL Server Management Studio
  • Logging & Monitoring Tools — e.g., ELK stack, Grafana.

2. Docker and Containers

  • Install Docker Desktop to build and run containers locally.
  • Use Docker Compose to orchestrate multiple microservices and dependencies.
  • Containers package your microservices with all dependencies ensuring consistency across environments.

3. Git Repositories

  • Use Git for version control.
  • Host repositories on GitHub or other Git platforms.

4. Branching Strategy

  • Use a branching model to organize work and releases.

  • Common strategies:

  • Git Flow: Feature branches, develop branch, release branches, main/master branch.

  • GitHub Flow: Main branch + short-lived feature branches.
  • Trunk Based Development: Frequent small merges to main.
  • Branch naming examples: feature/user-auth, bugfix/login-error, release/v1.0.

Tips

  • Always pull latest changes before starting work.
  • Create pull requests / merge requests for code reviews.
  • Use .gitignore files to avoid committing sensitive or unnecessary files.

🌿 Different Types of Branching Strategies

1. Git Flow

  • Uses multiple branches: master (production), develop (integration), feature branches, release branches, and hotfix branches.
  • Good for complex projects with planned releases and multiple environments.

2. GitHub Flow

  • Simple model with a single main branch.
  • Developers create short-lived feature branches off main.
  • After code review, branches are merged back into main.
  • Ideal for continuous deployment and simpler workflows.

3. Trunk-Based Development

  • All developers work on a single trunk (often main or master).
  • Small, frequent commits with feature toggles to manage incomplete features.
  • Supports continuous integration and fast delivery.

4. Feature Branching

  • Developers create branches for each feature or bugfix.
  • Branches live until feature is complete, then merged back.
  • Helps isolate development and reduce conflicts.

5. Release Branching

  • Create branches specifically for preparing releases.
  • Stabilize and test release branch before merging to production branch.
  • Allows bug fixes without disrupting ongoing development.

6. Forking Workflow

  • Developers fork the main repository to their own copy.
  • Make changes in the fork, then create pull requests to original repo.
  • Common in open-source projects.