ZuloOne
English
CabinetAccount
Sign in
Menu

Create a web service

Updated

A web service is an RPC the business layer publishes at /api/rest/{Name}. It lives in your model and dies with it. It is not a data entity (/odata/{Collection} — a record projection with $filter).

Note

Do not add a controller in the platform core for a country or customer operation. The longer page — flags, Headers / RawBody, status exceptions — is A model's web services.

How to#

Three files in WebServices/<Name>/:

  1. <Name>.webservice.json — kind: "WebService", plus parameters (the contract). Each parameter is request or response (isResponse).
  2. <Name>Service.script.json — the script binding.
  3. <Name>Service.cs — the user partial. The platform generates <Name>Request / <Name>Response and <Name>Service : WebServiceScriptBase<<Name>Request>.

Override Any when the verb does not matter (Get / Post / Put / Delete fall through to it). Handlers are Task. A body with nothing to await returns Task.FromResult(...).

public partial class ZatcaCsrService
{
    public override Task<object?> Any(ZatcaCsrRequest request)
    {
        var result = ScriptServices.Get<IZatcaCsr>().Create(
            request.VatNumber ?? "", request.Organization ?? "");
        return Task.FromResult<object?>(new ZatcaCsrResponse
        {
            Ok = true,
            Csr = result["csrPem"],
        });
    }
}

GetService<T>() works as in any script. Outbound traffic still goes by channel name — Send an outbound call. A non-200 is throw new WebServiceStatusException(502, new { error = "…" }).

Three switches on the object: isEnabled (default true — disabled is indistinguishable from an unknown name), isDevOnly (stands only), requireExplicitRoles (an empty permission matrix is otherwise public to any authenticated caller). An operation that returns a secret wants the last two on.

Bump modelVersion in the same change. Call it with POST /api/rest/{Name}. Compile is the ordinary models compile.

Warning

parameters is replaced wholesale. A designer PUT whose body omits "parameters" erases the contract: the DTOs become empty classes and the body stops compiling.

What's not there yet#

A web service is not a place to hide CRUD of a dictionary. That is a data entity. Cookie is withheld on purpose; Authorization is passed through.

Where next#

Was this page helpful?