29.09.2022 17:00 UTC Watch the Event

Dynamic JavaScript API Client Proxies

It is typical to consume your HTTP APIs from your JavaScript code. To do that, you normally deal with low level AJAX calls, like $.ajax, or better abp.ajax. ABP Framework provides a better way to call your HTTP APIs from your JavaScript code: JavaScript API Client Proxies!

Static vs Dynamic JavaScript Client Proxies

ABP provides two types of client proxy generation system. This document explains the dynamic client proxies, which generates client-side proxies on runtime. You can also see the Static JavaScript API Client Proxies documentation to learn how to generate proxies on development time.

Development-time (static) client proxy generation has a slight performance advantage since it doesn't need to obtain the HTTP API definition on runtime. However, you should re-generate the client proxy code whenever you change your API endpoint definition. On the other hand, dynamic client proxies are generated on runtime and provides an easier development experience.

A Quick Example

Assume that you have an application service defined as shown below:

using System;
using System.Threading.Tasks;
using Volo.Abp.Application.Dtos;
using Volo.Abp.Application.Services;

namespace Acme.BookStore.Authors
{
    public interface IAuthorAppService : IApplicationService
    {
        Task<AuthorDto> GetAsync(Guid id);

        Task<PagedResultDto<AuthorDto>> GetListAsync(GetAuthorListDto input);

        Task<AuthorDto> CreateAsync(CreateAuthorDto input);

        Task UpdateAsync(Guid id, UpdateAuthorDto input);

        Task DeleteAsync(Guid id);
    }
}

You can follow the web application development tutorial to learn how to create application services, expose them as HTTP APIs and consume from the JavaScript code as a complete example.

You can call any of the methods just like calling a JavaScript function. The JavaScript function has the identical function name, parameters and the return value with the C# method.

Example: Get the authors list

acme.bookStore.authors.author.getList({
  maxResultCount: 10
}).then(function(result){
  console.log(result.items);
});

Example: Delete an author

acme.bookStore.authors.author
    .delete('7245a066-5457-4941-8aa7-3004778775f0') //Get id from somewhere!
    .then(function() {
        abp.notify.info('Successfully deleted!');
    });

AJAX Details

JavaScript client proxy functions use the abp.ajax under the hood. So, you have the same benefits like automatic error handling. Also, you can fully control the AJAX call by providing the options.

The Return Value

Every function returns a Deferred object. That means you can chain with then to get the result, catch to handle the error, always to perform an action once the operation completes (success or failed).

AJAX Options

Every function gets an additional last parameter after your own parameters. The last parameter is called as ajaxParams. It is an object that overrides the AJAX options.

Example: Set type and dataType AJAX options

acme.bookStore.authors.author
    .delete('7245a066-5457-4941-8aa7-3004778775f0', {
        type: 'POST',
        dataType: 'xml'
    })
    .then(function() {
        abp.notify.info('Successfully deleted!');
    });

See the jQuery.ajax documentation for all the available options.

Service Proxy Script Endpoint

The magic is done by the /Abp/ServiceProxyScript endpoint defined by the ABP Framework and automatically added to the layout. You can visit this endpoint in your application to see the client proxy function definitions. This script file is automatically generated by the ABP Framework based on the server side method definitions and the related HTTP endpoint details.

See Also

In this document
Mastering ABP Framework
Mastering ABP Framework Book

Build maintainable .NET solutions by following software development best practices using ABP.

See Details