Skip to content

Interface

In this section the type of the API adapter is defined and configured accordingly. The Type list offers seven types: REST, SOAP, Library, XSD, Database, Messaging and GraphQL.

The types of an API adapter 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 a REST API is the Base Url of the endpoint, for example https://restcountries.com/v3.1.

The Interface tab of a REST adapter

SOAP

To set up a SOAP API you need a WSDL schema. The Source is Url or File. The most common source is a URL, and then you only enter the URL.

A SOAP adapter with the source Url

If the WSDL definition is not available at a URL, you can upload it as a file. With File as the Source, a File Type of File lets you Upload WSDL file or use Add Existing to take one from the resources of the application. The other file type is a zip:

A SOAP adapter with the source File

The two options are:

  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 API adapter allows 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.

The Library type has these fields: Api Class Full Path, Repository Path, Binary files (Add Existing, or Upload and add binary files) and Packages (Add...).

The Interface tab of a Library adapter

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.

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

If 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. The XSD type has an XSD Location (File by default), Resources (Add Existing) and Upload XSD file.

The Interface tab of an XSD adapter

Database

Database with nothing else selected accesses the application's own database, whose configuration zAppDev already handles. Check External to use another database. Then you choose the Database Type, MSSQL, MariaDB, MySQL or Oracle, and enter the Connection String.

An external Database adapter

Messaging

Messaging connects to a message broker. The Provider is RabbitMQ, the only one in the list, and you enter the Url, the Vhost and the Exchange.

The Interface tab of a Messaging adapter

GraphQL

GraphQL needs only the Url of the endpoint.

The Interface tab of a GraphQL adapter

Security

Security settings can be set if needed. They are meant for the types that contact external endpoints that usually require authorization, REST and SOAP. The Type list offers:

  • None
  • Basic
  • oAuth
  • Certificate
  • Bearer
  • UseDefaultCredentials

The security types

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. Fill in Username and Password.

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 Grant Type list offers Password (a username and password) and WebServer.

The oAuth settings with the Password grant type

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 with a Password and a Certificate File, which you add with Add Existing or Upload Certificate.

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.

Bearer

A Bearer authorization needs only a Token.

UseDefaultCredentials

UseDefaultCredentials has nothing to configure. It uses the default credentials of the identity that runs the application.