JSON API Client Features

useClient() provides managed APIs around the JsonServiceClient instance registered in Vue App's with:

app.provide('client', client)

Which maintains contextual information around your API calls like loading and error states, used by @servicestack/vue components to enable its auto validation binding. Other functionality in this provider include:

let { 
    api,            // Send a typed API request and return results in an ApiResult<TResponse>
    apiVoid,        // Send a typed API request and return empty response in a void ApiResult
    apiForm,        // Send a FormData API request and return results in an ApiResult<TResponse>
    apiFormVoid,    // Send a FormData API request and return empty response in a void ApiResult
    loading,        // Maintain loading state whilst API Request is in transit
    error,          // Maintain API Error response in reactive Ref<ResponseStatus>
    setError,       // Set API error state with summary or field validation error
    addFieldError,  // Add field error to API error state
    unRefs          // Returns a dto with all Refs unwrapped
} = useClient()

Typically you would need to unwrap ref values when calling APIs, i.e:

let client = new JsonServiceClient()
let api = await client.api(new Hello({ name:name.value }))


This is unnecessary in useClient api* methods which automatically unwraps ref values, allowing for the more pleasant API call:

let api = await client.api(new Hello({ name }))


But as DTOs are typed, passing reference values will report a type annotation warning in IDEs with type-checking enabled, which can be avoided by explicitly unwrapping DTO ref values with unRefs:

let api = await client.api(new Hello(unRefs({ name })))


setError can be used to populate client-side validation errors which the SignUp.mjs component uses to report an invalid submissions when passwords don't match:

const { api, setError } = useClient()
async function onSubmit() {
    if (password.value !== confirmPassword.value) {
        setError({ fieldName:'confirmPassword', message:'Passwords do not match' })

Form Validation

All @servicestack/vue Input Components support contextual validation binding that's typically populated from API Error Response DTOs but can also be populated from client-side validation as done above.

Explicit Error Handling

This populated ResponseStatus DTO can either be manually passed into each component's status property as done in /Todos:

<template id="TodoMvc-template">
    <div class="mb-3">
        <text-input :status="store.error" id="text" label="" placeholder="What needs to be done?"
                    v-model="store.newTodo" v-on:keyup.enter.stop="store.addTodo()"></text-input>
    <!-- ... -->

Where if you try adding an empty Todo the CreateTodo API will fail and populate its store.error reactive property with the APIs Error Response DTO which the <TextInput /> component checks for to display any field validation errors matching the field in id adjacent to the HTML Input:

let store = {
    /** @type {Todo[]} */
    todos: [],
    async refreshTodos(errorStatus) {
        this.error = errorStatus
        let api = await client.api(new QueryTodos())
        if (api.succeeded)
            this.todos = api.response.results
    async addTodo() {
        this.todos.push(new Todo({ text:this.newTodo }))
        let api = await client.api(new CreateTodo({ text:this.newTodo }))
        if (api.succeeded)
            this.newTodo = ''
        return this.refreshTodos(api.error)

Implicit Error Handling

More often you'll want to take advantage of the implicit validation support in useClient() which makes its state available to child components, alleviating the need to explicitly pass it in each component as seen in razor-tailwind's Contacts.mjs Edit component for its /Contacts page which doesn't do any manual error handling:

const Edit = {
    template:/*html*/`<SlideOver @done="close" title="Edit Contact">
    <form @submit.prevent="submit">
      <input type="submit" class="hidden">
        <ErrorSummary except="title,name,color,filmGenres,age,agree" class="mb-4" />
        <div class="grid grid-cols-6 gap-6">
          <div class="col-span-6 sm:col-span-3">
            <SelectInput id="title" v-model="request.title" :options="enumOptions('Title')" />
          <div class="col-span-6 sm:col-span-3">
            <TextInput id="name" v-model="request.name" required placeholder="Contact Name" />
          <div class="col-span-6 sm:col-span-3">
            <SelectInput id="color" v-model="request.color" :options="colorOptions" />
          <div class="col-span-6 sm:col-span-3">
            <SelectInput id="favoriteGenre" v-model="request.favoriteGenre" :options="enumOptions('FilmGenre')" />
          <div class="col-span-6 sm:col-span-3">
            <TextInput type="number" id="age" v-model="request.age" />
    <template #footer>
      <div class="flex justify-between space-x-3">
        <div><ConfirmDelete @delete="onDelete">Delete</ConfirmDelete></div>
        <div><PrimaryButton @click="submit">Update Contact</PrimaryButton></div>
    setup(props, { emit }) {
        const client = useClient()
        const request = ref(new UpdateContact(props.contact))
        const colorOptions = propertyOptions(getProperty('UpdateContact','Color'))

        async function submit() {
            const api = await client.api(request.value)
            if (api.succeeded) close()
        async function onDelete () {
            const api = await client.apiVoid(new DeleteContact({ id:props.id }))
            if (api.succeeded) close()

        const close = () => emit('done')
        return { request, enumOptions, colorOptions, submit, onDelete, close }

This effectively makes form validation binding a transparent detail where all @servicestack/vue Input Components are able to automatically apply contextual validation errors next to the fields they apply to:

Example using apiForm

An alternative method of invoking APIs is to submit a HTML Form Post which can be achieved with Ajax by sending a populated FormData with client.apiForm() as done in vue-mjs's SignUp.mjs for its /signup page:

import { ref } from "vue"
import { leftPart, rightPart, toPascalCase } from "@servicestack/client"
import { useClient } from "@servicestack/vue"
import { Register } from "../mjs/dtos.mjs"

export default {
    <form @submit.prevent="submit">
      <div class="shadow overflow-hidden sm:rounded-md">
        <ErrorSummary except="displayName,userName,password,confirmPassword,autoLogin" />
        <div class="px-4 py-5 bg-white dark:bg-black space-y-6 sm:p-6">
          <div class="flex flex-col gap-y-4">
            <TextInput id="displayName" help="Your first and last name" v-model="request.displayName" />
            <TextInput id="userName" label="Email" placeholder="Email" help="" v-model="request.userName" />
            <TextInput id="password" type="password" help="6 characters or more" v-model="request.password" />
            <TextInput id="confirmPassword" type="password" v-model="request.confirmPassword" />
            <CheckboxInput id="autoLogin" v-model="request.autoLogin" />
        <div class="pt-5 px-4 py-3 bg-gray-50 dark:bg-gray-900 text-right sm:px-6">
          <div class="flex justify-end">
            <FormLoading v-if="loading" class="flex-1" />
            <PrimaryButton :disabled="loading" class="ml-3">Sign Up</PrimaryButton>
    props: { returnUrl:String },
    setup(props) {
        const client = useClient()
        const { setError, loading } = client
        const request = ref(new Register({ autoLogin:true }))

        /** @param email {string} */
        function setUser(email) {
            let first = leftPart(email, '@')
            let last = rightPart(leftPart(email, '.'), '@')
            const dto = request.value
            dto.displayName = toPascalCase(first) + ' ' + toPascalCase(last)
            dto.userName = email
            dto.confirmPassword = dto.password = 'p@55wOrd'
        /** @param {Event} e */
        async function submit(e) {
            if (request.value.password !== request.value.confirmPassword) {
                setError({ fieldName: 'confirmPassword', message: 'Passwords do not match' })
            // Example using client.apiForm()
            const api = await client.apiForm(new Register(), new FormData(e.target))
            if (api.succeeded) {
                location.href = props.returnUrl || '/signin'
        return { loading, request, setUser, submit }

Which method to use is largely a matter of preference except if your form needs to upload a file in which case using apiForm is required.

AutoForm Components

We can elevate our productivity even further with Auto Form Components that can automatically generate an instant API-enabled form with validation binding by just specifying the Request DTO to create the form for, e.g:

<AutoCreateForm type="CreateBooking" formStyle="card" />

Create a new Booking

help ?? useLabel

The AutoForm components are powered by your App Metadata which allows creating highly customized UIs from declarative C# attributes whose customizations are reused across all ServiceStack Auto UIs.

TypeScript Definition

TypeScript definition of the API surface area and type information for correct usage of useClient()

/** Maintain loading state whilst API Request is in transit */
const loading: Ref<boolean>

/** Maintain API Error in reactive Ref<ResponseStatus> */
const error: Ref<ResponseStatus>

/** Set error state with summary or field validation error */
function setError({ message, errorCode, fieldName, errors }: IResponseStatus);

/** Add field error to API error state */
function addFieldError({ fieldName, message, errorCode }: IResponseError);

/** Send a typed API request and return results in an ApiResult<TResponse> */
async function api<TResponse>(request:IReturn<TResponse> | ApiRequest, args?:any, method?:string);

/** Send a typed API request and return empty response in a void ApiResult */
async function apiVoid(request:IReturnVoid | ApiRequest, args?:any, method?:string);

/** Send a FormData API request and return results in an ApiResult<TResponse> */
async function apiForm<TResponse>(request:IReturn<TResponse> | ApiRequest, body:FormData, args?:any, method?:string);

/** Send a FormData API request and return empty response in a void ApiResult */
async function apiFormVoid(request: IReturnVoid | ApiRequest, body: FormData, args?: any, method?: string);