APIs

This page describes how to model APIs in the canonical model:

services and their methods
resources and resource methods (endpoints)
how types are used as requests and responses
how method types from base models define HTTP semantics

The focus is on the canonical model (.cmn). How platforms map these APIs to concrete technologies (REST, messaging, RPC, …) is configured in platform profiles and cartridges, covered on Profiles & platforms (.profil).

This page assumes you are familiar with the basics of data modelling in Entities & DTOs and with the general modeling principles from the Modeling overview.

1. Services

A service groups related operations that represent business capabilities. In the canonical model, services are technology-neutral:

they do not mention HTTP methods, URLs or transport protocols;
they are expressed in terms of types and operations;
platforms decide how to implement them (REST, messaging, RPC, …).

Typical use cases for services:

business service interfaces
application services orchestrating domain logic
ports in a hexagonal architecture

1.1 Service methods

Service methods:

have a name,
may have parameters,
return a result type or void-like outcome,
can be annotated with stereotypes or other metadata (via platforms).

Service methods usually consume and return complex types or simple types from your model. The exact DSL syntax is covered in the CMN reference; conceptually you should think of a service as a clean, technology-agnostic interface.

Platforms can later map service methods to:

Java interfaces,
REST controllers or gRPC services,
message handlers, workflows, …

depending on the platform configuration.

2. Resources and endpoints

While services represent business operations, resources describe externally visible APIs, typically in a REST style.

A resource defines:

a resource path (for example /hello),
one or more resource methods (endpoints),
the request and response types for each method,
references to resource method types that define HTTP semantics.

2.1 Resource definition

A simplified example (similar to the quickstart) is:

text

resource /hello as Greeting {

    create()
    read()

}

Here:

/hello is the resource path,
Greeting is the type that represents the resource,
create() and read() are resource methods that reference method types imported from a base model.

Conceptually, this describes an API where:

POST /hello creates a greeting,
GET /hello retrieves greeting data,

with concrete HTTP details provided by the method types.

2.2 Resource method types

Resource methods use method types defined in imported base models. For example, a base API model might define:

text

methodtype create POST consumes='*' produces=Id success=201
methodtype read   GET instance=true produces='*' success=200 errorResponse=ErrorResponse

These method types describe:

the HTTP method (POST, GET),
whether the method operates on a collection or instance (instance=true),
request/response semantics (body, status codes),
optional error handling concepts (errorResponse=ErrorResponse).

Your resource simply writes create() or read() and inherits all these details. This keeps your canonical model concise and lets you reuse consistent semantics across many resources.

Platforms use this information to generate:

OpenAPI operations for each endpoint,
controller methods with the correct HTTP annotations,
error handling and response types,
client stubs or SDKs.

2.3 Raw vs. opinionated method types

The Base facility ships two kinds of resource method types:

Raw method types – pure HTTP verbs without any defaults:

cmn

methodtype get    GET
methodtype post   POST
methodtype put    PUT
methodtype patch  PATCH
methodtype delete DELETE

Use these when you really need full freedom (special HTTP contracts, non-standard status codes or payload structures). All details such as consumes, produces, instance and responses must then be modelled explicitly in each resource method.

Opinionated method typess – REST-oriented defaults that cover most CRUD and query scenarios:

cmn

methodtype create  POST consumes='*' produces=Id success=201
methodtype start   POST consumes='*' produces=Id success=201
methodtype execute POST consumes='*' produces='*' success=201
methodtype read    GET instance=true produces='*' success=200 errorResponse=ErrorResponse
methodtype update  PUT instance=true consumes='*' produces='*' success=200
methodtype delete  DELETE instance=true produces=Id success=200
methodtype query   GET produces='*[]' success=200 paging=true sorting=true responseContext=ResponseContext errorResponse=ErrorResponse
methodtype list    GET produces='*[]' success=200 paging=true sorting=true errorResponse=ErrorResponse

In practice:

prefer the opinionated methods for standard REST-style APIs,
fall back to the raw methods when the default semantics do not fit your use case.

2.4 Requests and responses

The request and response types of a resource method are usually derived from:

the resource's main type (Greeting in the example),
additional method-specific types, if the DSL or platform defines them,
method type configuration (for example indicating whether the request body is required, what is returned on success, etc.).

From the modeling perspective you usually have to decide:

which type represents the resource as a whole,
whether you need specialised request/response DTOs or can reuse the same type for both directions,
which base method type best matches the behaviour you need (create, read, update, delete, search, …).

3. Relationship between services and resources

Services and resources can be used independently or together:

In a pure REST style, you may focus on resources and resource methods only.
In a layered architecture, you might:
- define services as your internal API,
- expose parts of those services through resources,
- let platforms generate controllers from resources and service interfaces from services.

From the canonical model's point of view there is no hard coupling between services and resources. The exact relationship is typically defined by platform profiles and generators, and may vary between projects.

Important points:

Services capture business intent and often map to application or domain services.
Resources capture external contracts (HTTP APIs, web endpoints, etc.).
Both reuse the same underlying types (entities, DTOs, value objects), which keeps your model consistent.

4. Paths, operations and naming

When you design your APIs in CMN, keep the following in mind:

Use clear, stable resource paths that reflect your domain concepts.
Choose method names that express intent (create, read, findBy..., search...) – these names can be used by platform profiles to assign stereotypes or special behaviour.
Keep HTTP-specific details in method types and platform profiles instead of repeating them everywhere in your models.

Platform profiles can define conventions, such as:

automatically adding a findBy stereotype to methods whose name starts with findBy,
mapping certain method names to HTTP verbs or query patterns,
treating some resources as read-only or admin-only based on name or stereotypes.

This lets you control API behaviour and implementation details centrally without cluttering your canonical model with low-level attributes.

5. How APIs are validated and generated

Validation and generation for APIs work like for the rest of the model, with some API-specific aspects.

5.1 Validation

JoinedWorkz Studio and cartridges can check, for example:

that resource paths are unique within a given scope,
that method types used in resources are defined and compatible with the resource type,
that referenced request/response types exist and are valid,
that naming and layering conventions are respected (depending on the platform).

Errors are shown directly on the relevant resource or method in the editor, so you can quickly fix issues.

5.2 Generation

Typical generators for API-related models include:

OpenAPI generators – create OpenAPI 3 documents from resources and types,
controller generators – create controllers or handlers that implement the resource methods,
client generators – create client stubs based on the same canonical model.

Because APIs are defined on the canonical model, you can:

reuse the same model to generate both server and client artifacts,
target different frameworks (e.g. Spring Boot, other REST frameworks) by switching platforms,
keep your API documentation and implementation in sync.

6. Next steps

From here you can:

read about Components to see how APIs are grouped into deployable units;
explore Profiles & platforms (.profil) to understand how platforms interpret services and resources;
consult the CMN reference for the exact syntax of service, resource and method definitions.

APIs ​

1. Services ​

1.1 Service methods ​

2. Resources and endpoints ​

2.1 Resource definition ​

2.2 Resource method types ​

2.3 Raw vs. opinionated method types ​

2.4 Requests and responses ​

3. Relationship between services and resources ​

4. Paths, operations and naming ​

5. How APIs are validated and generated ​

5.1 Validation ​

5.2 Generation ​

6. Next steps ​