Modules and entities

Modules, entities and option sets give an API its shape. A module groups the endpoints of one business area. Inside a module, each entity is a Dataverse table you expose, with its own actions. Option sets expose choice lists that apps use to fill drop-downs. Their names become part of the addresses callers use, so choose them with care.

Modules

A module groups the entities, process actions and queries of one area of the API, for example a Sales module with accounts, contacts and quotes, and a Service module with cases.

The module name is the first segment of every address in the module:

What	Address
An entity action	/sales/account/create
A record action	/sales/account/{id}/get
A module process action	/sales/recalculatepricing
A query	/sales/openopportunities

Addresses are always lowercase, whatever the case of the name.

Add a module

1. In the tree, select Modules.
2. Select Add module (or Module on the command bar).
3. Enter the Module name and save.

Module names use 3 to 50 letters and numbers and start with a letter, for example SalesOrders. Each name must be unique in the API, and the name of the built-in system module is reserved.

Rename a module

You can rename a module from its Summary page. API Studio warns you before you confirm:

Callers reach this module’s actions at name/<entity>/<action>. Once this version is published, they need the new name in those addresses.

Empty names and names already used by another module are refused.

Renaming changes callers’ addresses

Renaming a module changes the address of every action and query in it once the version is published. A rename breaks existing callers, so publish it as a new major version and tell the teams that call the API. See Publishing and versions.

Entities

Entities are the Dataverse tables a module exposes. Each entity gets its own set of actions, and the entity’s Dataverse logical name (for example account or incident) is the second segment of its addresses.

Add entities to a module

1. In the module, select Entities.
2. Select Add entities. The Add/Remove Entities From Dynamics panel lists the tables in your environment.
3. Select Add next to each table you want to expose (or Remove to take one out), then close the panel.

Then add actions to each entity:

Action	What callers can do	Example
Read	Get one record, with the fields you choose	A customer reads their open case.
Create	Add a record from what they send	The website’s contact form creates a lead.
Update	Change a record from what they send	A customer updates their phone number.
Delete	Remove a record	A user removes a saved address.
Process	Run a Dataverse action on a record	Approve a quote.
Upload	Attach a file to a record	A portal user uploads a scanned ID to their case.
Download	Get a file attached to a record	A customer downloads the invoice attached to their order.

An entity can have several actions of the same kind, for example two read actions that return different fields for different callers. Each action has its own name, which becomes the last segment of its address. See Actions.

Option sets

Option sets are fixed lists of choices, for example a case priority of Low, Normal or High. Exposing them lets apps load the current values and labels instead of hard-coding them.

Kind	Where you add it	Address
Global option set	Option Sets in the tree	/optionsets/{name}
Entity option set	Option sets of an entity	/{module}/{entity}/optionsets/{name}

To add global option sets, select Option Sets > Add option set. The Add Option Sets From Dynamics panel lists the option sets in your environment; select Add for each one, or Preview to see its values first.

Option sets also serve as the types of inputs, arguments and user properties that hold a choice.

Rename an option set

You can rename an option set in the API. The underlying Dataverse option set does not change; only the name callers use does. API Studio warns you:

Callers read this option set at optionsets/name. Once this version is published, they need the new name in that address.

Empty and duplicate names are refused. As with modules, publish a rename as a new major version.

Example

A customer-portal API for a service organization might look like this:

Module	Entities and actions	Queries	Option sets
Portal	contact: Read profile, Update profile	myCases (cases of the signed-in contact)	—
Service	incident: Create submit, Read get, Upload attach, Download file; Process escalate	openCases	incident › prioritycode
—	—	—	Global: casetype

The portal then calls addresses such as POST /service/incident/submit, GET /portal/mycases and GET /optionsets/casetype.

Related

• Actions
• Queries
• Calling the API