You don't need any networking background to use Mittelware. This page explains the handful of ideas the rest of the docs build on. Five minutes here will make everything else easier. If you already know what a request, a proxy and a status code are, skip ahead to Getting started.

What happens when an app talks to the internet#

Whenever an app shows you something from the internet, such as a web page, a weather forecast or a list of users, it asks a computer somewhere else for that information. There are always two sides:

• The client is the app that asks. A browser, a mobile app, a script or a tool like Postman can all be clients.
• The server is the computer that answers.

The question the client sends is called a request. The answer the server sends back is called a response. Together they are one HTTP exchange, and Mittelware shows each one as a single row on its Flows page.

Think of ordering at a restaurant. The request is your order ("one fake user, please"). The response is the plate that comes back.

What is inside a request#

Every request has the same few parts:

A URL itself has pieces too. In https://api.example.com:8443/v1/users?page=2:

• https is the scheme (http is plain, https is encrypted).
• api.example.com is the domain, which names the server.
• 8443 is the port, a numbered door on that server. If it's missing, the scheme decides: 443 for https, 80 for http.
• /v1/users is the path, which says which thing you want.
• ?page=2 is the query string.

What is inside a response#

Status codes you will see most#

The first digit tells you the story: 2xx is success, 3xx is a redirect, 4xx means the client did something wrong, and 5xx means the server did.

What is JSON#

Most apps that talk to servers exchange data as JSON, a simple text format of names and values:

{
  "id": 1,
  "name": "Leanne Graham",
  "email": "Sincere@april.biz"
}

Curly braces hold an object, square brackets hold a list, and text goes in quotes. Mittelware shows JSON as a collapsible tree so you can read it easily.

What is a proxy, and what does Mittelware do#

Normally a request goes straight from your app to the server. A proxy is a go-between that you place in the middle. The request goes to the proxy first, and the proxy passes it on.

Without a proxy:   your app  ───────────────────────►  server

With Mittelware:   your app  ───►  Mittelware  ───►  server
                               (sees everything,
                                can change things)

Because Mittelware sits in the middle, it can do three things:

1. Watch. Every request and response that passes through is recorded, so you can read them on the Flows page. This answers questions like "what is my app really sending?"
2. Pause. It can hold a request before it leaves, so you can look at it or edit it by hand.
3. Change. With rules, it can block a request, rewrite part of it, or replace the response with one you wrote. You test how your app copes with a slow server, a 500 error or different data, without touching the server's code.

All of this happens on your own computer. The proxy listens at 127.0.0.1 (the address a computer uses to mean "myself") on a port, 8080 by default, so other devices on your network can't reach it.

What is HTTPS, and why does Mittelware ask about a certificate#

HTTPS is the encrypted version of HTTP. Encryption scrambles the traffic so nobody between you and the server can read it. That is great for privacy, but it also means a tool in the middle sees only scrambled data.

For you to see inside your own HTTPS traffic, Mittelware creates a small certificate of its own and asks your computer to trust it. Then it can unscramble the traffic from your apps, show it to you, and scramble it again on the way out. The certificate stays on your device and applies to your user account only. HTTPS & certificates explains it in full, including how to remove it.

Glossary#

Ready to try it?#

Next up is Getting started: you'll install Mittelware, watch a real request travel through it, and change a response yourself in about ten minutes.