MicroServices - henk52/knowledgesharing GitHub Wiki

https://nats.io/

1. Synchronous request–response a) HTTP / REST

How it works

Services communicate via HTTP APIs (usually JSON).

Very common and easy to debug.

Rust tooling

Servers: axum, actix-web, warp

Clients: reqwest, hyper

Pros

Simple and widely supported

Easy to integrate with non-Rust services

Cons

Higher latency than binary protocols

Tight coupling (caller waits for response)

Use when

CRUD-style APIs

Low to moderate traffic

b) gRPC (HTTP/2 + Protobuf)

How it works

Strongly typed RPC calls using Protocol Buffers.

Supports streaming.

Rust tooling

tonic (most popular)

prost for Protobuf

Pros

Fast, binary, strongly typed

Excellent for internal service-to-service calls

Cons

Harder to debug than HTTP

Less browser-friendly

Use when

Internal microservice communication

Performance and schema safety matter

2. Asynchronous messaging (event-driven) a) Message brokers (queues & pub/sub) RabbitMQ (AMQP)

Rust

lapin

Use case

Task queues, work distribution

Pros

Reliable delivery

Supports routing patterns

Apache Kafka

Rust

rdkafka

Use case

Event streams, logs, analytics

Pros

High throughput

Durable event storage

Cons

Operational complexity

NATS

Rust

async-nats

Use case

Lightweight pub/sub, request-reply

Pros

Very low latency

Simple to operate

b) Cloud-native queues

Examples:

AWS SQS/SNS (aws-sdk-rust)

Google Pub/Sub

Azure Service Bus

Pros

Managed infrastructure

Scales automatically

Cons

Vendor lock-in

Higher latency than in-memory systems

3. Peer-to-peer and lightweight protocols a) WebSockets

How it works

Persistent bidirectional connections

Rust

tokio-tungstenite, axum::ws

Use when

Real-time updates

Streaming data

b) Raw TCP / UDP

How it works

Custom binary protocols

Rust

tokio, bytes, bincode, serde

Pros

Maximum performance

Full control

Cons

Reinventing reliability, security, and tooling

Use when

Ultra-low latency systems (e.g. trading, games)

4. Shared data systems (indirect messaging) a) Redis (pub/sub, streams)

Rust

redis

Use cases

Pub/sub

Distributed locks

Event streams (Redis Streams)

b) Database-backed messaging

PostgreSQL LISTEN / NOTIFY

Polling tables

Pros

No extra infrastructure

Cons

Not suitable for high throughput

5. Service mesh & sidecar-based communication

How it works

Communication handled by infrastructure (e.g. Envoy)

Services talk over localhost

Examples

Istio, Linkerd (Kubernetes)

Rust impact

Your Rust service uses plain HTTP/gRPC

Mesh handles retries, mTLS, observability

6. Serialization formats (important choice)

Common options in Rust:

JSON – simple, verbose

Protobuf – fast, typed, cross-language

MessagePack – compact, flexible

CBOR – binary JSON

Avro – schema-based (Kafka)

7. Choosing the right method (quick guide) Requirement Recommended Simple APIs HTTP + JSON High-performance internal RPC gRPC Event-driven architecture Kafka / NATS Task queues RabbitMQ / SQS Real-time updates WebSockets Ultra-low latency TCP + custom protocol Cloud-managed SNS/SQS / PubSub
8. Common real-world combination

Most Rust microservice systems use multiple methods:

gRPC for internal service calls

Kafka or NATS for events

HTTP for external APIs

APIs

Four types of API

• OS api

• Library API

• Remote API

• Web API

• Web API examples

  • SOAP - outdated
  • REST - Representational State Transfer
    • URL + JSON based.
  • GraphQL
    • Allows you to choose which fields you want in the reply.
    • Also flexible requests.
    • Support subscriing to field changes.
    • JSON
  • gRPC
    • binary - Protobuf
    • over HTTP/2 - bi-directional.

Structure of REST API Request

• Method: HTTP Verb (GET, POST, PUT, DELETE, ...)
  • Patch?
• URL: Location of the resource + parameters
• Headers: Meta-data of the request (User Agent...)
  • Token?
• Body: Contents of the request(optional)

Structure of REST API Response

• Status code: 200(Success) ...
• Headers: Meta-data of the response(Content type...)
• Body: Contens of the respose(optional)

Beeceptor

• REST API Mocking
• Very easy to use
• No coding required
• Free. Limited to 50 requests per day.

https://beeceptor.com/

Postman

• REST API Client
• Can set verb, URL, headers, body
• view full response
• Very easy to use
• A lot of advanced features.

My recommendation for Fedora 43 Use case Best choice Closest to Postman Insomnia Fast + local + Git-friendly Bruno Browser/self-hosted Hoppscotch VS Code workflow Thunder Client CLI workflow HTTPie

flatpak install flathub com.usebruno.Bruno flatpak run com.usebruno.Bruno

The verbs for CRUD

For the API server, each Verb constitute a completely different API/path/operation

• Create - Post
  • No parameters in URL
  • data in body
• Read - Get
  • Max ~1000charater in URL
  • No body
• Update - Put
  • No query string parameters.
  • Data in body.
  • If the resource does not already exists, then this should behave as a POST.
    • Though could there exists security issue in doing it like that?
  • Should be Idempotent.
• Delete - Delete
  • No body.

Verb	CRUD	Body?	Parameters in
DELETE	Delete	No	URL
GET	Read	No	URL
POST	Create	Yes	Body
PUT	Update	Yes	Body

Rarely used verbs

• PATCH - Similar to PUT, but with partial updates.
  • e.g. might contain only a subset of the full data of the PUT.
• HEAD - Same as GET, but without the body in the response.
  • e.g. use to verify an entity exist.
• OPTIONS - Describe the the available verbs for the URL.

URL Structures

e.g. https://www.myapp.com/api/v1/

• Should be https

• should have 'api' in its name

  • e.g api.ebay.com
  • or https://language.gogleapis.com/v1/documents:analyzeEntities

• if the URL does not contain the 'api' word then it should include as the first path: '/api/'

  • e.g. www.myapp.com/api

• Version strategy

  • It can be provide three ways
    • in the URL - preferred
      • e.g. https://www.myapp.com/api/v1
    • in the header
    • as a parameter
      • ?version=4
  • only natural numbers
    • positive
    • no decimals
  • can be prefixed with 'v'

• Entity

  • REST deals with resources/entities
  • Should be one word, no more.
  • Never a verb.
  • Only nouns, resources, entities.
  • e.g.
    • https://www.myapp.com/api/v1/order
    • https://www.myapp.com/api/v2/employees
      • TODO why is 'order' single but 'employees' plural?
  • Singular vs Plural
    • There is no concrete answer.
    • Best practice: Always prefer readability and ease of use
      • When you expect a single entity in the reply user '/order'
      • When you expect multiple entities in the answer use '/orders'

• ID parameters(optional)

  • When dealing with a specific entity, the next part is the entity ID.
  • The ID is part of the URL.
  • e.g. /api/order/17
  • Relevant for: GET, PUT, DELETE
  • Not used for POST.

• Sub entity(optional)

  • Used for acessing entities that are dependent on other entities.
    • e.g. get all the items of order 17
      • the items are the sub entities.
    • Do Not use: /api/v1/ItemsInOrder/17
      • Not readable, long url
      • Not simple
    • Sub entity should come after the id
      • e.g. /api/v1/order/17/items
      • this URL is hierarchical, easu to understand.
    • The same goes for sub-sub entities, etc.

• Query Parameters(Optional)

  • Used to query the entities in the GET method.
  • Comes at the end of the URL after a '?'

	Query parameters	ID parameter
Location	Ath the end of the URL	End or middle of the URL
Param count	0..N parameters	1 parameter
Example	/api/v1/orders?user=john	/api/v1/order/17
Return found value	May retun 0..N entities	Must return exactly 1 entity
If not found	That is fine	Error!

TODO the 'May retun 0..N entities' does that mean it might not even return a reply? Or is it to make it clear it might return 0 entities???

Response codes

• 1xx - Information repsonse
  • No one is using it.
• 2xx - Success
• 3xx - Redirections
  • Usually implemented by a lowlevel components.
    • e.g. web server
• 4xx - Client errors
• 5xx - Server errors

There are many non-standard error codes used by companies like XXX

Response code 2xx - Success

• 200 - Ok
• 201 - Created
  • The request has been fulfilled
  • A new intity has been created
• 202 - Accepted
  • Has been accepted and is pending processing
  • Processing might not be complete.
  • No notification is given when the processing is completed.
• 204 - No content
  • Request was fulfilled but no content was sent back.
  • Should not include body.
  • Used mainly when updating large entity or large connection of entities.
  • 204 vs 200 when GET returns no entity.
    • Recommendation: Stick with 200.

Response code 4xx - Client error

• 400 - Bad request
  • e.g.
    • parameters can't be valiedated (e.g. negative age)
    • JSON can't be parsed
  • Used with all verbs
  • Consider using RFC 7807 - Problems detail
    • Standard for returning machine-readable data about the problem.
      • e.g. json format.
• 401 - Unauthorized
  • The client is not authorized to accce sthe entity.
  • Authorization is required.
  • Not to be confused with 403-Forbidden
• 403 - Forbidden
  • Authorization failed.
    • Authorization flow
      • client req -> server
      • server -> client: 401
      • client authorize req -> server
      • server -> client: 403
• 404 - page not found
  • The entity specified in th request was not found
    • Used when a specific entity was looked for using the path, not the query parameters.
  • Used with all verbs.

Response code 5xx - Server error

• 500 - Internal server error.
  • Something bad happened whhile processing the request
  • for security reasons the client is not given any information about the error.
  • used with all verbs.
• Other 5xx status codes are susually not used, or are low level.

Monitoring API

• requests/s
• number of failures
• latency . CPU
• RAM
• number of users
• number of sessions
• Geographic distribution

Documenting the API with OpenAPI

• Formerly known as swagger

• Describes

  • Endpoints
  • Parameters
  • Authentication
  • Information abou the API

• Can be used to:

  • Provide documnetation and test bed for developers.
  • Generate client libraries.
  • Generate the API(Design-First)

• Can be automatically generated

• Compatible with many API platforms

Authentication and authotization

• Authentication (AuthN) - The user is who they say they are.
• Authorization (AuthZ) - What the authenticated user is allowed to do.

OAuth2

• Standard protocol for authenticationand authorization.

sequenceDiagram
  ClientApp->>ResourceServer : Anonymous request
  ResourceServer-->>ClientApp : Redirect client
  ClientApp->>AuthorizationServer : Please give me a token
  AuthorizationServer-->>ClientApp : request for credentials
  ClientApp->>AuthorizationServer : credentials
  AuthorizationServer->>AuthorizationServer : validate credentials
  AuthorizationServer-->>ClientApp : Access token
  ClientApp->>ResourceServer : Access token

• User - The user who wants to access protected resources in the API.

• Client App - app accessing the API

• Authorization Server - e.g. google

  • Must be familiar with the resource server.
  • other auth servers:
    • github
    • facebook?

• Resources server(API server)

  • Must register itself with the Authorization Server.

• https://auth0.com/docs/get-started/onboarding/self-service-m2m

• https://www.youtube.com/watch?v=tpIXmmV4ib4

• PKCE

  • used on mobile apps?

Scratchpad

• HATEOS - Hypermedia As The Engine Of Application State.
  • Each REST request returns related resources.
  • The client should not have prior knwoledge about other resources.
    • TODO seems to mean it conatins a _links section with references to other API URLs related to this call.

API Gatways

• Cloud
  • AWS - API Management
  • Azure - API Management
  • Google cloud - Apigee
• On-prem
  • WSO2 api manager
  • Tyk