Development Server: APIs and Deployment

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 00D000000000000

sf 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 aer

Session 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... done

Query records:

$ sf data query -q "SELECT Id, Name FROM Account" -o aer
┌────────────────────┬──────┐
│ ID                 │ NAME │
├────────────────────┼──────┤
│ 001aer000000001AAA │ Acme │
└────────────────────┴──────┘

Total number of records retrieved: 1.
Querying Data... done

Call Apex REST:

sf apex run rest -m GET -u /services/apexrest/MyService -o aer

A 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-run

Deployments 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.