Skip to content

Interface

In this section the type of the External API is defined and configured accordingly. The following five types are currently supported: REST APIs, SOAP APIs, Libraries (DLL), XSDs and Application Database. First we'll cover the different external type definitions and afterwards the security configuration that is can be applied in REST and SOAP API types.

Definition

REST

The only initial configuration for REST APIs, is to enter the Base URL of the endpoint.

e.g.

External API - REST

SOAP

To setup a SOAP API, a WSDL schema is needed and it can be provided either by URL or file. The most common source is usually a URL which is pretty simple.

e.g.

External API - SOAP

If for some reason the WSDL definition is not available at a URL, you can upload it as a file. When file is selected as a source then you have two options:

  1. Upload a WSDL file or select one from the application's resources
  2. Upload a Zip file or select one from the application's resources

A Zip file can be used when there are multiple WSDL that compose the SOAP API's definition. In this case the "Relative WSDL Path Inside ZIP file" must be set. It should point to the main/root WSDL file of the APIs structure.

Library

This type of External API allow you to use functionalities from .NET compiled DLLs. Use the upload button to upload any DLL files you want to use in your application. If any DLL files are already uploaded use the Add Existing link to add from your application resources.

Important

Make sure you add every DLL files that your main DLL depends on. Also note that .pdb files and .xml files should not be uploaded otherwise parsing errors may occur.

Now consider the following C# code:

using System;

namespace RatingCalculator
{
    public class Calculator
    {
        public static double WilsonScore(double up, double total, double confidence = 1.644853)
        {
            if (total <= 0 || total < up)
                return 0;

            double phat = up / total;
            double z2 = confidence * confidence;

            return (phat + z2 / (2 * total) - confidence * Math.Sqrt((phat * (1 - phat) + z2 / (4 * total)) / total)) / (1 + z2 / total);
        }
    }
}

Once this code is compiled and uploaded you must add the Namespace and Class to the API Class full path field:

External API - Library

This configuration allows your application to access the public static methods of the class.

Important

Please note that only the public and static methods of a class are available to access. Private methods and methods that require an instance of the class will not be accessible.

XSD

The XSD type is used when you only need to import external data structures to your application. Similar to the SOAP configuration you can select:

  1. To upload a single XSD file, or select from the resources a file that's already uploaded
  2. To upload a ZIP file with multiple XSD files, or select from the resources a file that's already uploaded

Also in case a ZIP file is uploaded the "Relative WSDL Path Inside ZIP file" must be set. It should point to the main/root XSD file of the structure:

External API - XSD

Application Database

This option does not have anything to configure since it will be accessing the application's database. The database configuration is already handled by zAppDev.

Security

Security settings are available and can be set if needed for REST and SOAP types. These types contact external endpoints that usually require authorization before accessing them. The most commonly used authentication methods are supported:

  • None
  • Basic
  • oAuth
  • Certificate

No Auth

This is the default option where you don't need any authorization to access the endpoint.

Basic Auth

Basic Authentication requires a verified username and a password to include in the request headers. Simply fill these two fields and you're good to go.

oAuth

OAuth authorization implements the oAuth 2.0 version and enables a third party owner to approve your authentication on behalf of the API you want to access. The following two grant types available for configuration:

  1. Using a username and password
  2. Using a Web Server

Below are the properties you can set with a short description:

Property Description
Client ID The client identifier given to the client during the Application registration process
Scope The scope to determine the of the permissions needed for the request. It might have multiple space-separated values
Access Token URL The endpoint for the resource server, which exchanges the authorization code for an access token
Password Type Permissions
Username The username...
Password ...and the password
Client Secret The client secret given to the client during the Application registration process
WebServer Type Permissions
Callback URL The Application’s callback URL that’s registered with the server
Authorization URL The endpoint for authorization server, which retrieves the authorization code

Certificate

Certificate authorization uses a client certifacate instead of username and password to authenticate and authorize users. Certificate authorization is configured using a Certificate File and Password.

Property Description
Certificate File The file containing the certificate. You may upload a new file or use an existing Resource.
Password The password or passphrase used while generating the client certificate. In case there is no password, leave it blank.