API3

API3 is a special collection of routes within APIEngine that allows execution of a subset of database stored procedures. The implementation is in APIEngine/API/_api3/ (v95 and earlier: sbn-services-framework; v96 and later: sbn-services).

Routes

All routes are declared on Api3Controller and require a token. The table shows v96 and later (APIEngine 1.0).

v96 and later: [DisableTryItOut] hides the Swagger Try-it-out button on the execute endpoints; use the API3 Viewer instead.

v95 and earlier: the api/v1/api3/... routes and api/v1/build/{id} do not exist. Execute is api/v1/{id} only (POST, PATCH, DELETE). list, api/list and api/v1/list without an id return every procedure, and GET api/build rebuilds every mapping. The help pages are the ASP.NET Help Page, which has no Try-it-out button.

Procedure prefix rules

Api3Model.IsValidProcedure rejects procs starting with t_ or l_; everything else is executable.

Schema generation (GetJSONSchema) is restricted to c_, g_, d_, is_. Active-active server switching engages only for c_ and d_ procs that take @s#ins/@s_ins. Dependency hyperlinks are emitted for v_, l_, c_, t_, g_ procedures.

Searching

Use the Search field to find an API3 procedure. If a procedure is followed by the Map button, it is out-of-date and should be remapped. Otherwise mapping is not needed.

Mapping is required by APIEngine before executing a stored procedure so it knows the input fields and expected result set in advance. If a procedure is not mapped before it is executed it will be mapped during execution. Procedures must be remapped after compiling if the input parameters or result set changed.

Click an API3 name to load the details:

1. Return Codes - return codes for this API3 call. Not recursive; codes from internal calls are not represented.
2. Dependencies - every stored procedure called from within. Dependencies on API3-compliant procs are hyperlinks.
3. JSON Schema - everything a developer needs to integrate the call.
4. Test - parameters for the selected procedure; JSON input is built in real time as values are entered.

Background mapping

v96 and later: API3MappingHostedService is a BackgroundService that runs every 10 seconds (TimeSpan.FromSeconds(10)). Each pass calls GetProcList() and rebuilds the JSON mapping object for any procedure whose database CompiledOn timestamp is newer than the cached CreatedOn. Procedures that fail to map are tracked in an in-memory fail list and skipped on subsequent passes until their CompiledOn changes; failures are logged.

v95 and earlier: there is no background mapping. A procedure is mapped when it is executed with no mapping file in App_Data, or when api/build/{id} is called. The list marks a procedure as outdated when its CompiledOn is newer than its mapping; remap it after recompiling.

Automatically mapped fields

APIEngine populates the following stored-procedure parameters from the caller's auth token. Do not supply them in the request body - they will be ignored or overwritten.

1. @userid - SBN user login (always mapped when authenticated as an SBN user).
2. @pc_id, @pc_ext, @pc_code, @pc_num - passcard identity (mapped when present on the token).
3. @pv_num, @pv_uadpr - pers_vru identity (mapped when present on the token).
4. @noaccess, @noprofile - forced to 0 unless OverrideAPISecurity is set in apiengine.settings.

Preauth tokens may only execute procedures that declare a preauth parameter; otherwise the call is rejected with UnauthorizedAccessException.

New API Calls in Release 94

New API calls were added for integrators: relay support, retrieving a user's phone and email, displaying active zones, and retrieving multiple event lists in a single dealer-restricted call.