Run and observe
Send requests to the real API
Test APIs sends a request from your browser to a system’s running API and checks the answer against its contract.
Open Test APIs in the appWhat Test APIs does
Test server gives other teams a stand-in for a system's API. Test APIs (next to it in the sidebar) does the reverse: it calls the system's running API. It follows the environment picked at the top of the page, like the rest of the app: pick one of the endpoints the system provides in that environment, fill in the request, and press Send. You see the answer, and under it whether the answer matches the contract.
The request goes straight from your browser to the API. Rabbinatix doesn't pass it on, so nothing about the request or the answer reaches our servers. It also means the API has to allow calls from this site (see Let this site call your API).
Open Test APIs in the sidebar and pick the system in System at the top right; it lists the systems that provide at least one endpoint, the same as Test server. From a system's page, Test APIs in its … menu opens it with that system picked.
Choose where requests go
Under Send to, pick one of four:
- Pick from health checks: requests go to the host of one of the environment's health checks. When the environment has tenants (such as IT and UK in Production), pick the tenant in Tenant. Only the scheme, host and port are used: a health check at
https://uk.site.com/healthzsends tohttps://uk.site.com. Each tenant has its own variables and sign-in. If the environment has no health check yet, add one on the system's Running tab. - Pick per environment: requests go to the environment's saved API address (see below).
- Use another address: requests go to an address you type (see below).
- Test server: requests go to the system's own test server, which answers with example data from the published contract. Try a request and the contract check before the real API runs. There is no environment to pick, and it has its own variables and sign-in.
Send to every tenant
With Pick from health checks and an environment that has more than one tenant, Send to every tenant sends the request as it is to each tenant at once, each with its own variables and sign-in. A table lists each tenant's answer, how long it took and whether it matches the contract, so a tenant that behaves differently stands out. A tenant that can't be sent to (a variable it has no value for, say) says why. Click a tenant's name to see its whole answer below. Each send goes in the History.
Set the API addresses
Each environment has its own address, such as http://localhost:3000 for Development or https://api.acme.com for Production.
- In Test APIs, pick the system and choose Pick per environment.
- Click Edit addresses. It opens by itself when the picked environment has no address yet.
- Under API addresses, type the address for each environment you want to call. Start it with
http://orhttps://and leave out the path: the endpoint's path is added for you. - Click Save addresses.
Anyone who can edit the system can change the addresses, with Development picked in the header (another environment shows them read-only). They are saved at once, also in organizations that review changes before publishing: an address isn't a change to the design.
Use another address
To call an API somewhere else for a while, such as your own build on http://localhost:8080, a teammate's machine or a preview deploy, choose Use another address and type it. The environment at the top doesn't change where it sends. Another address has its own variables and sign-in under Variables and sign-in, apart from each environment's, and it can use them, as in {{host}}.
The address you type is kept in this browser only, and the saved addresses don't change. A request in the History remembers where it went (another address, or a health check's tenant), so loading it sends to the same place again.
Outside Development, Test APIs lists the APIs of the release each system runs in that environment, and a system that isn't deployed there has none. Test server lists them the same way, but the test server itself always answers from the published design: an API changed since that release may answer differently.
A request in the History that went to another environment's address says so when you load it: pick that environment at the top to send it there again. A pasted cURL to another environment's address goes to it as another address, and the message says which environment it belongs to.
Copy and paste cURL
- Copy as picks what Copy gives: cURL, or code in JavaScript / TypeScript, Python, C#, Java, Go, PHP or Ruby, using only that language's standard library (Programming languages).
- Copy, under the request, copies it (as a
curlcommand unless you picked a language) to paste in a terminal, a ticket or a chat. The sign-in (theAuthorizationheader or the API key) and secret variables are shown as dots. Copy with secrets copies it with them: keep that one to yourself. - Paste cURL, next to Variables and sign-in, does the reverse. Paste a command, from a terminal, the browser's network tab (Copy as cURL) or another tool, and click Fill in the request. The endpoint is found by the method and the path at the end of the address. Its path values, query, headers, body and sign-in are filled in. The part of the address before the path picks where to send: an environment's saved address or a health check's when it is one of them, the test server, or else another address. Cookies and other headers a browser can't send are left out, and the message after it names them. The request isn't saved until you click Save, and a token in it is never saved.
If no API of the picked system has that method and path, it says so: pick the system that provides it at the top right, or add the API first.
Build the request
- Pick the environment at the top of the page. Its address is shown under Send to.
- Pick an endpoint in the list. It is grouped by API version, and the search box finds an endpoint by its method, path or summary.
- The request starts from the contract's examples, the same ones Try it uses on the reference page, or from your saved request when you saved one:
- Path values fill in the parts of the path such as
{orderId}. - Query and Headers are rows of names and values. The switch on each row sends it or leaves it out. Required ones are marked Required.
- Body is the JSON body, for methods that send one. A body that isn't valid JSON gets a warning but is still sent as typed, so you can see how the API handles it.
- Auth sets how the request signs in (see below).
- The full address, with every value filled in, is shown above the form.
- Start again from the examples puts the contract's examples back in the form.
You can also open it on one endpoint from elsewhere: Send to the real API on an endpoint's reference page, or next to Copy endpoint URL in Test server.
Save a request
Click Save next to Send to keep what you filled in for the endpoint. The next time you pick that endpoint, the form starts from your saved request instead of the contract's examples. Each endpoint keeps one saved request, and saving again replaces it.
- Save is off while the form matches what you saved, and turns on again as soon as you change something. The time you last saved is shown under the form.
- Saved requests are yours: teammates don't see them. They are kept with your account, so they follow you to another browser or computer. They go when you leave the organization.
- A token typed straight into Auth isn't saved. Put it in a Secret variable such as
{{token}}instead: the saved request keeps{{token}}, and the value stays in this browser. - Start again from the examples puts the examples back in the form without removing what you saved. Click Save to replace your saved request with them.
Variables
Values you use often, or don't want to type again, go in variables. Click Variables and sign-in, then Add variable, and give it a name and a value. Use it as {{name}} in the address, path values, query, headers, body and sign-in.
- Each environment has its own variables, so
{{token}}can hold a Development token and a different Production one. - A variable used but not defined in the environment stops Send and says so, for example {{token}} has no value in Development.
- Tick Secret to hide a value. It is shown as dots in the form and in the address, and never kept in the history.
Sign-in
Pick the kind of sign-in under Auth:
The kind the contract declares is picked for you. To avoid setting it on every endpoint, set the system's sign-in once under Variables and sign-in. Endpoints then start with Same as the system. Put tokens in a variable such as {{token}}: a token typed straight into the form isn't kept in the history.
The answer and the contract check
After Send, the tab shows the status, how long it took, the size, and the body (indented when it is JSON) and headers. Cancel stops a request that is still waiting. After 30 seconds without an answer it gives up.
Under the answer, the contract check says Matches the contract or Doesn't match the contract, with each mismatch in plain words and the field it is about:
- a status the contract doesn't declare, such as Status 503 is not one the contract declares
- a missing field, such as currency is missing
- a wrong type, such as items[].price should be integer but is string
- a value outside its list, or
nullwhere it isn't allowed - a field the contract doesn't list, as a note: a new field doesn't break anyone
It also checks the request you sent. If you edited it away from the contract (removed a required header, for example), it says so under The request we sent. That is a warning, not a failure: trying things out is the point. The check is the same one the contract watcher runs on real traffic, so both say the same thing.
History
The last 20 requests for the system are listed under History, newest first, with their status and when they were sent. Click one to load it back into the form, with its endpoint and environment. Clear empties it. Like variables, the history is kept in this browser only.
Let this site call your API
Browsers only let a page call an API on another address when the API allows it. This is called CORS. When the API doesn't allow it, the browser blocks the call and says nothing more. The tab then tries one plain call to the address to tell the cases apart:
- Your API answered, but doesn't let this site read the answer: the API is there and needs the headers below, or send from your computer (below).
- Nothing answered at this address: the API isn't running there, or a VPN or firewall is in the way (or the address starts with http:// and isn't on your computer).
- You're offline: nothing was sent.
Your API has to answer with these headers, both on the request itself and on the OPTIONS request the browser sends first:
Access-Control-Allow-Origin: <this site's address>
Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type
Access-Control-Expose-Headers: *List every custom header you send under Access-Control-Allow-Headers. The blocked-call message shows the exact headers for the request you sent. Without Access-Control-Expose-Headers the browser hides most response headers, and the tab says Some headers are hidden by the browser.
Turn it on for Development and test environments. In Express:
import cors from 'cors';
app.use(cors({ origin: 'https://<this site>', exposedHeaders: '*' }));In Spring:
@Bean
WebMvcConfigurer cors() {
return new WebMvcConfigurer() {
public void addCorsMappings(CorsRegistry r) {
r.addMapping("/**").allowedOrigins("https://<this site>").allowedMethods("*").allowedHeaders("*").exposedHeaders("*");
}
};
}In ASP.NET:
builder.Services.AddCors(o => o.AddPolicy("rabbinatix", p => p.WithOrigins("https://<this site>").AllowAnyMethod().AllowAnyHeader().WithExposedHeaders("*")));
app.UseCors("rabbinatix");In Go, with github.com/rs/cors:
handler := cors.New(cors.Options{
AllowedOrigins: []string{"https://<this site>"},
AllowedMethods: []string{"GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"},
AllowedHeaders: []string{"*"},
ExposedHeaders: []string{"*"},
}).Handler(mux)In FastAPI:
from fastapi.middleware.cors import CORSMiddleware
app.add_middleware(CORSMiddleware, allow_origins=["https://<this site>"], allow_methods=["*"], allow_headers=["*"], expose_headers=["*"])In Django, with django-cors-headers, in settings.py:
INSTALLED_APPS += ["corsheaders"]
MIDDLEWARE.insert(0, "corsheaders.middleware.CorsMiddleware")
CORS_ALLOWED_ORIGINS = ["https://<this site>"]
CORS_EXPOSE_HEADERS = ["*"]In Laravel, in config/cors.php:
'paths' => ['api/*'],
'allowed_methods' => ['*'],
'allowed_origins' => ['https://<this site>'],
'allowed_headers' => ['*'],
'exposed_headers' => ['*'],In Rails, with the rack-cors gem, in config/initializers/cors.rb:
Rails.application.config.middleware.insert_before 0, Rack::Cors do
allow do
origins "https://<this site>"
resource "*", headers: :any, methods: :any, expose: ["*"]
end
endIn Ktor:
install(CORS) {
allowHost("<this site>", schemes = listOf("https"))
anyMethod()
allowHeaders { true }
exposeHeader("*")
}In axum, with tower-http:
let cors = CorsLayer::new()
.allow_origin("https://<this site>".parse::<HeaderValue>().unwrap())
.allow_methods(Any)
.allow_headers(Any)
.expose_headers(Any);
let app = Router::new().merge(routes).layer(cors);Other things browsers block
- http:// addresses. This site is served over https://, and browsers block calls from it to http:// addresses, except
localhostand127.0.0.1. Settings and the tab warn about such an address. Use the API's https:// address. - Your computer and local network. Chrome may ask whether this site can reach devices on your local network, for
localhosttoo. Allow it and send again. - Cookies. Requests are sent without cookies, so an API that signs you in with a cookie doesn't work here. Use a token.
- Some headers. The browser sets headers such as
Host,Cookie,OriginandContent-Lengthitself. A row with one of those names says The browser doesn't let this be sent and is left out.
Send from your computer
None of the above applies when the request is sent from your own computer instead of this site: no CORS headers are needed, http:// and VPN addresses work, and every header of the answer can be read.
- In a terminal on your computer, run
npx -y rabbinatix relay. It shows a code, such ask7xm-p2qa-9fdz. - Under the endpoint's address, set Send through to This computer and type the code. It says Connected when it reaches the relay.
- Click Send as usual.
The relay listens on 127.0.0.1:4011, on your computer only. It takes calls only from this site and only with its code, which changes every time it starts, and sends nothing to Rabbinatix. Stop it with Ctrl+C. The choice and the code stay in this browser. More: The rabbinatix CLI.
Related
- Test serverEvery system gets a test server URL that answers like its declared endpoints, so frontends can start before the backend exists.
- Contract watcherDownload one file, start it in your frontend in development, and every real API call is checked against your contracts.
- Environments and deploymentsRecord which release of each system runs in each environment, see compatibility per environment, and check a release before you deploy it.
- APIs and contractsDeclare what providers offer and what consumers expect. Rabbinatix pairs them into contracts and checks them field by field.
