Logic API best practices

These practices come from projects where portals, mobile apps and partner systems depend on a Logic API. They keep the API predictable for the teams that call it and safe for the data behind it.

Design

• One module per business area. Sales, Service, Portal, not one module per table, and not one module for everything. Module names appear in every address, so pick short, stable names.
• Name actions for what callers do. submit, escalate, approve read better in an address than create1 or processaction. Names are 3–50 letters and numbers; addresses are lowercase, so openCases becomes /service/opencases.
• Return only what the app needs. Each read action and query returns the fields you choose. Leave out internal and sensitive fields; add a second read action for callers who need more.
• Prefer process actions for business operations. When an operation has rules, such as approving a quote or closing a case, expose a Dataverse action (or a logic flow exposed as a Dataverse action) instead of letting the app update status fields directly.
• Use Sliced queries for anything that can grow. Keep All for short lists such as statuses or team members.
• Fill in the Docs step. Titles and descriptions are what app developers read first.

Security

• Set an authorization policy on every endpoint. An endpoint without one is public. Before publishing, check the Access column of each list for Anyone and confirm each one is meant to be public.
• Use roles for “who”, preconditions for “which records”. A role says a caller is a partner; a precondition makes sure the partner only touches their own account’s records.
• Look up before you check. Use the Data Fetcher step to load what the precondition needs (the record’s status or owner) rather than trusting values the caller sends.
• Agree role names and user properties with the hosting team early. They supply them at sign-in; a mismatch shows up as 401 responses.
• Write error messages users can act on. “You can only change your own open cases” is better than “Validation failed”.

Versions

• Keep the draft clean. Fix issues as they appear; the header’s issues list takes you to each one. A draft with issues can’t be published.
• Minor for additions, major for anything that breaks callers. Renaming a module or option set, removing a field or tightening access are major changes.
• Write release notes on every published version, in terms app developers understand.
• Don’t delete old versions while apps still use them. Versions that others are built on can’t be deleted anyway.

Handover to app teams

• Generate the OpenAPI schema for every published version and share it with Calling the API and Responses and errors.
• Publish and generate the schema from your pipeline with the Logic Fabric CLI, so environments and documentation stay in step.

Checklist before publishing

• The header shows no issues and the draft is saved.
• Every endpoint has an authorization policy, or is public on purpose.
• Preconditions protect records callers must not change.
• Queries that can grow are Sliced.
• Docs are filled in; release notes are written.
• Changes that break callers go into a new major version.

Related

• Access control
• Publishing and versions
• Deploy & ALM best practices