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, maximum limit, sort field, and sort direction

Changes take effect immediately. The generated GraphQL schema updates in real time, and the Preview & Hints view reflects the new configuration without delay.

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(limit: 20) {
    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 supports two query operations. 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 appear as query entry points in the generated GraphQL schema. Consumers can discover and execute them.
• Disabled operations are invisible to consumers. They do not appear in schema introspection, and attempts to call them return an error.

An entity with all operations disabled is still part of your data model. Its data exists in MongoDB, its relations remain intact, and it can still be referenced through nested queries on other entities. 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.

Free plan operation limits

Free User

Free plan users have full access to operation exposure controls. The number of enabled operations is not limited by plan — only the number of projects and tables is constrained.

Pagination Defaults

Every list query supports offset-based pagination. The API design view lets you configure default pagination behavior per entity:

Setting	Description	Typical Range
Default limit	Number of records returned when the consumer does not specify a limit	10 -- 50
Maximum limit	Upper bound on the limit parameter to prevent excessive data transfer	100 -- 500
Default sort field	The attribute used for ordering when no sort is specified	Any sortable attribute
Default sort direction	ASC or DESC	Depends on the sort field

Consumers can override the default limit and sort in their queries, but they cannot exceed the maximum limit. If a consumer requests limit: 1000 and your maximum is set to 200, the response will contain at most 200 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 limit (10--20) to keep responses fast.
• Reference entities (e.g., countries, currencies) with small datasets can use a higher default limit (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 or sort by any fields that are not yet marked as filterable or sortable?

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	The query disappears from the schema; existing consumer queries fail
Change a query name	All consumers must update their queries to use the new name
Increase default limit	Consumers receive more records by default; response size grows
Decrease maximum limit	Consumers requesting large pages receive fewer records than expected
Change default sort field	The default ordering of results changes for consumers who do not specify a sort

Every API design change regenerates the schema immediately. The Runtime serves the updated schema, and the Preview & Hints view reflects changes in real time.

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, flags (sortable, filterable, searchable), 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.