Development Server: APIs and Deployment
aer server answers the Salesforce REST, SOAP, Tooling, Analytics, and Metadata APIs, so the Salesforce CLI, scripts, and integration tests can use it in place of an org. See Development Server for how to start the server.
API endpoints
The server exposes Salesforce-compatible REST and SOAP API endpoints. Point external tools, scripts, or integration tests at the local server instead of a Salesforce org.
Authentication
Connect to the local server using the Salesforce CLI:
$ sf org login web -r http://127.0.0.1:8080 -a aer
Successfully authorized admin@aer.local with org ID 00D000000000000sf org login web waits for a login in a browser. In a script or agent session, use a pre-shared session token instead.
The default credentials are:
- Username:
admin@aer.local(override with--username) - Password:
password(override with--password)
REST writes require an authenticated session. Create, update, and delete requests run as the user the session token resolves to, and a request with no valid session is rejected with 401. A create that does not supply a record type is assigned the profile’s default record type, matching Salesforce.
Pre-shared session tokens
A client that cannot complete the browser login flow, such as a CI job or a
script, can be given a token in advance. Pass --seed-session-token (or set
AER_SEED_SESSION_TOKEN) to register that token as an authenticated session
for the default admin user at startup:
aer server force-app/main/default \
--seed-session-token '00D000000000000!AQEAQ.local.dev.token'The token must start with 00D000000000000! and continue with letters,
digits, underscores, or periods. Log in with the Salesforce CLI using the same
token:
SF_ACCESS_TOKEN='00D000000000000!AQEAQ.local.dev.token' \
sf org login access-token --instance-url http://127.0.0.1:8080 -a aerSession tokens are accepted in both the Bearer and the classic
OAuth <sessionId> authorization schemes.
REST API examples
Create a record:
$ sf data create record -s Account -v "Name='Acme'" -o aer
Successfully created record: 001aer000000001AAA.
Creating record for Account... doneQuery records:
$ sf data query -q "SELECT Id, Name FROM Account" -o aer
┌────────────────────┬──────┐
│ ID │ NAME │
├────────────────────┼──────┤
│ 001aer000000001AAA │ Acme │
└────────────────────┴──────┘
Total number of records retrieved: 1.
Querying Data... doneCall Apex REST:
sf apex run rest -m GET -u /services/apexrest/MyService -o aerA packaged @RestResource class is served under its namespace, at
/services/apexrest/<namespace>/<urlMapping>, as in a subscriber org.
The server supports composite requests, batch requests, the SObject
Collections API, Bulk API 1.0 and 2.0, and POST /process/approvals for
submitting records for approval. A record written through any REST or Bulk
endpoint runs the same triggers, flows, workflow rules, and validation rules
an Apex insert would, and each row reports its own errors. The default API
version is 67.0; override it with --api-version.
A query result larger than the batch size (2,000 records by default, or 200
to 2,000 set with Sforce-Query-Options: batchSize=) returns
done: false and a nextRecordsUrl, as Salesforce does, and queryAll
returns deleted records. Bulk API 1.0 query jobs support PK chunking
(Sforce-Enable-PKChunking) and queryAll, jobs with concurrencyMode
Serial run their batches one at a time, and CSV query results use
Salesforce’s format.
Tooling API
Tooling queries return ApexClass, ApexSettings,
ApexCodeCoverage, ApexCodeCoverageAggregate, ApexOrgWideCoverage, and
MetadataComponentDependency, whose rows come from aer’s dependency graph.
MetadataContainer, ApexClassMember, and ContainerAsyncRequest implement
the container save path used by IDE integrations, and runTestsSynchronous
and runTestsAsynchronous run tests and record coverage. runTestsAsynchronous
accepts suiteNames, so sf apex run test --suite-names works against the
server.
POST /tooling/apexCompileResults type checks the program and returns each
class, interface, and trigger that does not compile, with each problem’s
line, column, and message, and IsValid on ApexClass and ApexTrigger is
false for those. GET /tooling/symbols returns Apex type metadata as
typeStubs: category=builtin for the standard library, database for your
Apex, and dynamic for the classes generated from record-triggered flows,
filtered by namespace and name.
Analytics API
The analytics/reports and analytics/dashboards endpoints run reports and
dashboards loaded from your source. Report results use the factMap shape
the Salesforce Analytics API returns. A dashboard response includes the
metadata of each component and its report results, run as the authenticated
user unless the server was started with --use-dashboard-running-user.
The Analytics Download API returns images:
/analytics/download/report/<reportId>.png returns a report’s chart, and
/analytics/download/lightning-dashboard/<dashboardId>.png returns a
dashboard with each of its components. As in Salesforce, these are browser
URLs that authenticate with the session cookie, so log in through the
Lightning frontend first. aer draws its own chart layouts, so the images
differ from Salesforce’s in detail.
Deploy metadata to the running server
To apply changes as you save files, start the server with --watch instead. Use a deployment when the change comes from somewhere other than the server’s source directories, when you are testing an integration that deploys to Salesforce, or when you want to use an existing tool that is built on the Salesforce APIs, such as a deployment pipeline.
The server implements the Metadata API deploy endpoints, so a standard deployment from the Salesforce CLI updates the running server without a restart:
sf project deploy start --source-dir force-app/main/default/classes -o aer
# Validate without applying
sf project deploy start --source-dir force-app -o aer --dry-runDeployments are extracted and imported with the same metadata walker the server uses at startup, so any type aer loads from source can be deployed: Apex classes and triggers, objects and fields in metadata or source format, flows, flexipages, workflow rules, permission sets, profiles, custom metadata records, queues, labels, value sets, static resources, Visualforce pages, email templates, reports, and dashboards.
Remote site settings and external credentials deploy too, so a deployment can add the setting that permits a callout.
Each deployment compiles Apex against the merged schema, validates
package.xml members the way the Metadata API does, migrates storage tables
for deployed objects, and commits only on success. A deployment fails only
for errors in the components it deploys. A class it does not deploy that no
longer compiles is marked invalid, as Salesforce does. Deployments queue in
Pending status, apply one at a time, run as the deploying user, and roll
back on failure. A deployment that changes only Apex does not trigger a schema
reload. Deployed classes keep their ApexClass Id across the Tooling API,
the Data API, and Apex.
The Metadata API’s describeMetadata, listMetadata, createMetadata,
updateMetadata, and upsertMetadata calls are answered too, and a write is
applied the same way a deployment is.