Simple Object Designer Documentation
Index

API Configuration

This page covers detailed configuration options for API endpoints created with Simple Object Designer.

API Page Card

The API Page Card provides full configuration access:

Accessing

  1. Open API Endpoints list
  2. Click on an API to open its card
  3. Review and modify settings

Card Sections

Section Purpose
General Basic API settings
Entity Settings Name and caption configuration
Fields Field selection and mapping

General Settings

Table Information

Field Description
Table No. Source table (read-only after creation)
Table Name Source table name

API Group

Organize APIs into logical groups:

Group Typical Content
Sales Customer, Sales Order APIs
Purchasing Vendor, Purchase Order APIs
Inventory Item, Location APIs
Finance G/L, Journal APIs
Custom Your custom APIs

Creating Custom Groups

Enter any group name:

  • Groups are created on first use
  • Use consistent naming
  • Keep groups manageable

Entity Settings

Entity Name

The singular resource name:

Requirements:

  • Must be unique across your extension
  • Use camelCase convention
  • No spaces or special characters

Examples:

  • customEquipment
  • trainingRecord
  • workOrder

Entity Set Name

The plural collection name:

Requirements:

  • Typically the plural of entity name
  • Used for collection endpoints
  • Must be unique

Examples:

  • customEquipments
  • trainingRecords
  • workOrders

Entity Caption

Human-readable name:

Purpose:

  • Appears in API documentation
  • Shows in BC API metadata
  • Helps users understand the API

Entity Set Caption

Collection caption:

Purpose:

  • Describes the collection
  • Appears in API metadata

Field Configuration

Field List

The field list shows the fields available on the API page:

Column Description
Field Name Table field name
Type Field type
Class AL field class (Normal / FlowField / etc.)
Included Whether exposed in API
ObsoleteState Whether the source field is obsolete

Including/Excluding Fields

Toggle field inclusion:

  1. Select field row
  2. Change Included status
  3. Or check/uncheck in the list

The Class column indicates if a field is a FlowField. FlowFields are automatically calculated when included in an API endpoint, so their values are always current. However, each FlowField adds a calculation per record returned, which can impact performance. Only include FlowFields that consumers actually need.

Field Name Mapping

Each API page field has an OverrideName property that controls the JSON property name in the API. Edit it on the field's settings (the list does not display it as a column).

Why override:

  • Simplify technical names
  • Remove prefixes/suffixes
  • Follow consumer conventions

Example:

  • Table field: "Ext Customer Reference Hgd"
  • API field: "customerReference"

Key Fields

Primary key fields are automatically included:

  • Cannot be excluded
  • Required for record identification
  • Used in URL for single record access

Endpoint-Level Settings

Read-Only Endpoint

The API as a whole can be marked ReadOnly, which exposes only GET operations and rejects POST / PATCH / DELETE.

SOD does not currently provide per-field read-only or required flags. Field-level requirements come from the underlying table's NotBlank / validation triggers, not from API page configuration.

Navigation / $expand

The pages SOD generates do not declare navigation properties or $expand relations. Each entity is exposed independently; if you need cross-entity expansion, consume multiple endpoints and join on the client.

Deep insert is therefore also unsupported. You cannot create a parent record and its child records in a single request.

To work with a parent table and a child sub-table — a customer master table and its ship-to addresses, for example — create one API for the parent and a separate API for the child, then POST to each independently.

Include in Filter (Data Queries)

Fields inside a Data Query carry a per-field Include in Filter setting. It is narrower than it sounds:

  • It is only relevant when the Data Query is exposed as an API and you want to filter through URL-based OData parameters.
  • Its purpose is to let that field be used as a URL parameter for filtering in API calls.
  • If you are not doing URL/OData filtering, you do not need to enable it.

What it does not do:

  • It does not present a dialog to the user when the query is opened.
  • It does not pre-select fields in the Business Central list filter box, and has no effect on the BC UI list at all.

Filtering Configuration

Filterable Fields

By default, all exposed fields are filterable:

  • Supports $filter OData option
  • Various operators (eq, ne, gt, lt, etc.)
  • Field type determines operators

Optimizing Filters

Consider:

  • Indexed fields for better performance
  • Limiting filter complexity
  • Documenting recommended filters

Validation Settings

Insert Validation

When consumers POST new records:

  • Required fields checked
  • Data types validated
  • Business rules applied (if configured)

Update Validation

When consumers PATCH records:

  • Field-level validation
  • Partial updates supported
  • Concurrency checking (if enabled)

Templates Are Not Applied

Business Central templates — Item Templates, Customer Templates and the like — are not applied when a record is created through a SOD table API.

  • A POST performs a standard insert. No template is applied, even when a matching template exists.
  • Entering the generated API page number into Business Central's "API Setup" screen does not make BC apply the template on creation.

The supported workaround: expose the template itself as its own API endpoint, and have the consuming application read it and write the template-driven field values explicitly onto the record it creates.

API Versioning

In SOD

SOD doesn't provide explicit versioning, but you can:

  • Create multiple APIs with versioned names
  • customerV1, customerV2
  • Maintain backward compatibility

Best Practice

  • Plan for versioning from start
  • Document API versions
  • Deprecate gracefully

Testing Configuration

Before Publishing

  1. Review all settings
  2. Verify field selection
  3. Check entity names

After Publishing

  1. Test endpoint URL
  2. Verify operations work
  3. Check data correctness

Test Checklist

Test Expected Result
GET collection Returns records
GET single Returns one record
POST Creates new record
PATCH Updates record
DELETE Removes record

Configuration Best Practices

Naming Conventions

  • Use consistent prefixes for custom APIs
  • Follow RESTful naming patterns
  • Document naming standards

Field Selection

  • Include only necessary fields
  • Consider API consumers' needs
  • Balance completeness vs performance

Groups Organization

  • Group by business area
  • Keep groups cohesive
  • Don't over-fragment

Security Considerations

  • Exclude sensitive fields
  • Consider data classification
  • Review exposed data regularly