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.
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.
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.
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:
The two options are:
- Upload a WSDL file or select one from the application's resources
- 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...).
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:
- To upload a single XSD file, or select from the resources a file that's already uploaded
- 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.
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.
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.
GraphQL¶
GraphQL needs only the Url of the endpoint.
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
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.
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.









