Clients and type generation

The full contract of the public API is published as OpenAPI 3.1:

• Live: https://api.mirac-ozdemir.com/openapi.json (also available as /openapi-public.json). The response is cacheable (max-age=300) and open to CORS.
• On this site: the API Reference, generated from the same contract.

The contract contains only the 7 public operations in this documentation. It includes the Turkish descriptions, examples and a detailed JSON Schema of the tool definition format.

TypeScript types

Generate the types with a single command using openapi-typescript:

npx openapi-typescript https://api.mirac-ozdemir.com/openapi.json -o src/api/schema.d.ts

Use the generated types with a type-safe fetch wrapper (openapi-fetch):

import createClient from 'openapi-fetch';
import type { paths } from './api/schema';

const client = createClient<paths>({ baseUrl: 'https://api.mirac-ozdemir.com' });

const { data, error } = await client.POST('/v1/public/tools/by-key/{key}/calculate', {
  params: { path: { key: 'kdv' } },
  body: { inputs: { amount: '1000', mode: 'exclusive', vatRateOption: 'standard' } },
});
if (error) throw new Error(error.error.code);
console.log(data.data.result);

Tip

Commit the schema output to the repo and refresh it in CI; you will notice at build time when the contract changes. Backward-compatible additions do not break the types.

Client generation for other languages

Since the contract is standard OpenAPI, OpenAPI Generator or similar tools work:

Python

npx @openapitools/openapi-generator-cli generate -i https://api.mirac-ozdemir.com/openapi.json -g python -o ./mo-client

C#

npx @openapitools/openapi-generator-cli generate -i https://api.mirac-ozdemir.com/openapi.json -g csharp -o ./MoClient

PHP

npx @openapitools/openapi-generator-cli generate -i https://api.mirac-ozdemir.com/openapi.json -g php -o ./mo-client

Java

npx @openapitools/openapi-generator-cli generate -i https://api.mirac-ozdemir.com/openapi.json -g java -o ./mo-client

In the generated clients, decimal fields are of string type; convert them yourself to your language’s decimal type (Decimal, decimal, BigDecimal).

Importing into API clients

You can import the OpenAPI address directly:

• Postman: Import → Link → https://api.mirac-ozdemir.com/openapi.json.
• Insomnia: Create → Import → From URL.
• Bruno: Import collection → OpenAPI.
• Swagger UI / Redoc: give the address directly; CORS is open.

Example requests and responses for every operation are ready in the contract. To try things in the browser, you can also use the Playground.