API Design

The API design area controls how your domain model is exposed as a GraphQL API. Not every entity or operation needs to be public. This is where you shape the consumer-facing API contract — deciding which queries exist, what they are called, and how they behave by default.

API design sits between modelling and runtime. The Modelling Board and Tables & Attributes define what your domain looks like structurally. API design determines what consumers can actually reach.

Overview

When you open the API design view, you see a list of all tables in your current project. Each table row exposes configuration controls for:

• Query naming — the GraphQL query names consumers use to fetch data
• Operation exposure — which query types (list, detail) are enabled
• Pagination defaults — default page size, sort field, and sort direction

Changes take effect immediately: the mock API and the Preview & Hints view use the new configuration at once.

ws-api-01-overviewMissing

API design view showing per-entity query configuration.

Query Naming

Mockomat generates query names automatically from your entity names. The default convention follows standard GraphQL practice:

• List query — plural form of the entity name (e.g., products, customers, orderItems)
• Detail query — singular form of the entity name (e.g., product, customer, orderItem)

Both names are fully customizable. You can override the defaults to match your frontend team's conventions or your organization's naming standards.

Why Naming Matters

Query names are part of the API contract. They appear in every GraphQL request your consumers write:

query {
  products(pageSize: 20) {
    items {
      id
      name
      price
    }
  }
}

If you rename products to catalogItems after consumers have integrated, every query that references products will break. Choose names deliberately, and treat them as stable identifiers rather than labels.

Naming Guidelines

Guideline	Example	Rationale
Use camelCase	orderItems, not order_items	Matches GraphQL conventions
Be specific	activeProducts, not items	Reduces ambiguity across entities
Match domain language	invoices, not billingRecords	Aligns with how your team talks about the data
Keep singular/plural consistent	product / products	Consumers expect this symmetry

ws-api-02-query-namingMissing

Query name configuration for list and detail operations.

Operation Exposure

Each entity gets a list and a detail query by default. You control whether each operation is enabled or disabled independently:

Operation	Purpose	Default
List query	Fetch a paginated collection of records	Enabled
Detail query	Fetch a single record by identifier	Enabled

Enabling and Disabling Operations

Toggle operations on or off per entity. The effect is immediate:

• Enabled operations can be called by consumers under their name.
• Disabled operations answer every call with an error saying the operation is disabled.

An entity with all operations disabled is still part of your data model: its mappings and relations remain intact. Disabling operations only removes direct query access.

When to Disable Operations

• Internal entities that exist only to support relations (e.g., a join table for m:n relations) often do not need their own queries.
• Draft entities that are not yet ready for consumer use can be disabled temporarily.
• Restricted entities that should only be accessible through a parent entity's nested query (e.g., OrderItem accessed only via Order.items).

ws-api-03-operation-togglesMissing

Operation toggles for enabling and disabling list and detail queries.

Operation limits

Free User

Every plan has full access to operation exposure controls. The number of operations per project and of custom operations per table depends on your plan — see [Account and Plans](/en/account/).

Pagination Defaults

Every list query supports page-based pagination (page, pageSize). The API design view lets you configure the defaults per operation:

Setting	Description	Typical Range
Default page size	Records per page when the consumer sends no pageSize	10 -- 50
Default sort field	The attribute used for ordering when no sort is specified	Any attribute bound to a data column
Default sort direction	ASC or DESC	Depends on the sort field

Consumers can override the page size and sort in their queries. The page size is capped at 100 for every operation: a request for pageSize: 1000 returns at most 100 records.

Choosing Defaults

Pagination defaults shape the initial consumer experience. Consider:

• High-traffic entities (e.g., products in a catalog) benefit from a smaller default page size (10--20) to keep responses fast.
• Reference entities (e.g., countries, currencies) with small datasets can use a higher default page size (50--100) since consumers often need the full list.
• Sort field should reflect the most natural ordering. For time-series data, sort by createdAt DESC. For alphabetical listings, sort by name ASC.

ws-api-04-pagination-defaultsMissing

Pagination default configuration per entity.

GraphQL Schema Generation

Mockomat generates a GraphQL schema automatically from your model and API design configuration. The schema generation process follows a direct mapping:

API Design Setting	Schema Effect
Enabled list query	Adds a collection query to the schema root
Enabled detail query	Adds a single-record query to the schema root
Query name	Becomes the exact query field name
Attribute types	Map to GraphQL scalar types (String, Int, Float, Boolean)
Relations	Generate nested object types in the schema
Pagination settings	Define default argument values

The schema is regenerated every time you change an API design setting. You do not need to trigger a build or deploy step — the Runtime serves the updated schema immediately.

GraphQL vs REST

Mockomat generates GraphQL APIs by default. The mock runtime serves GraphQL at:

POST /mock/{slug}/graphql

REST-style operations are available through the Export feature, which generates full backend code from your model. The API design view focuses exclusively on GraphQL operation configuration.

Schema introspection

Paid User

Paid plan users can share their project's GraphQL endpoint with frontend teams. Consumers can use standard GraphQL introspection queries to discover the schema, which reflects your API design configuration exactly.

Design Principles

API design decisions compound over time. A well-designed API surface reduces integration friction and support burden. The following principles help you make decisions that remain stable as your model evolves.

Start Narrow

Expose fewer operations initially. It is always easier to add a new query than to remove one that consumers already depend on. Begin with the minimum set of queries your frontend needs, and expand coverage as the model stabilizes.

Name Intentionally

Query names are contracts, not labels. Before committing to a name, ask:

• Would a developer unfamiliar with this project understand what this query returns?
• Does this name conflict with any other query in the schema?
• Is this name stable enough to survive the next iteration of the model?

Validate Before Exposing

Use the Preview & Hints view to confirm that each enabled operation behaves correctly before sharing the endpoint with consumers. Check that:

• The response structure matches expectations
• Pagination defaults produce reasonable page sizes
• Sort order is intuitive for the data type
• No unresolved hints remain for the entity

Think Like a Consumer

Step outside the modeller's perspective. Consider:

• What queries would a frontend developer write to build a listing page?
• What queries would they need for a detail view?
• Would they need to filter by a field that has no parameter yet, or sort by a field that is not bound to data yet?

This perspective check often reveals missing configuration before consumers encounter it.

Causality: API Design to Consumer Experience

Every setting in the API design view has a direct, traceable effect on the consumer experience. Understanding this causality helps you predict the impact of changes before making them.

API Design Action	Downstream Effect
Enable a list query	Consumers can fetch paginated collections of that entity
Disable a list query	Calls to it answer an error; existing consumer queries fail
Change a query name	All consumers must update their queries to use the new name
Change the default page size	Consumers who send no pageSize receive a different number of records (at most 100)
Change default sort field	The default ordering of results changes for consumers who do not specify a sort
Add a parameter	Consumers can filter by it; unknown arguments are answered with BAD_USER_INPUT

Every API design change applies immediately: the Runtime and the Preview & Hints view use the new configuration at once.

ws-api-05-causality-flowMissing

Causality diagram: API design settings flow to schema and consumer experience.

Workflow Integration

API design is not a standalone step. It connects to every other workspace area:

1. Model your domain on the Modelling Board — create tables, define attributes, establish relations.
2. Configure attributes in Tables & Attributes — set types, the Searchable flag, and data mappings.
3. Design your API surface here — name queries, toggle operations, set pagination defaults.
4. Validate behavior in Preview & Hints — run queries, review hints, confirm correctness.
5. Test with real queries in the Runtime — execute the same queries consumers will use.
6. Export when ready via Export — generate backend code from your validated model.

Changes in earlier stages propagate forward. Adding a new attribute in the table editor automatically makes it available in the schema. Removing a relation updates the schema to reflect the change. The API design view gives you control over what is exposed, but the underlying structure comes from the model.

ws-api-06-workflow-integrationMissing

API design in the context of the full workspace workflow.

Iteration workflow

Registered User

Follow short design-validate cycles. After changing a query name or toggling an operation, open the preview immediately to confirm the effect. Small, verified changes are safer than large batch updates.

API governance

Enterprise User

Enterprise teams should establish naming conventions and operation exposure policies before modelling begins. Document which entity types require list queries, which require detail queries, and what pagination limits are acceptable. Treat the API design view as a governance checkpoint in your review process.

Contract stability

Developer / Integrator

If you are integrating Mockomat-generated APIs into a downstream application, treat the API design configuration as the source of truth for the contract. Monitor query names and operation exposure settings for changes, and validate your integration against the preview before each release cycle.