How to create a Webservice

Overview

A web services include any software, application, or cloud technology that provides standardized web protocols (HTTP or HTTPS) to interoperate, communicate, and exchange data messaging – usually XML (Extensible Markup Language) – throughout the internet.

In other words, web services are XML-centered data exchange systems that use the internet for A2A (application-to-application) communication and interfacing. These processes involve programs, messages, documents, and/or objects.

A key feature of web services is that applications can be written in various languages and are still able to communicate by exchanging data with one another via a web service between clients and servers. A client summons a web service by sending a request via XML, and the service then responses with an XML response. Web services are also often associated with SOA (Service-Oriented Architecture).

A web service supports communication among numerous apps with HTML, XML, WSDL, SOAP, and other open standards. XML tags the data, SOAP transfers the message, and WSDL describes the service’s accessibility.

  • SOAP is an XML-based Web service protocol to exchange data and documents over HTTP or SMTP (Simple Mail Transfer Protocol). It allows independent processes operating on disparate systems to communicate using XML.
  • REST provides communication and connectivity between devices and the internet for API-based tasks. Most RESTful services use HTTP as the supporting protocol.

(Retrived from https://www.cleo.com/blog/knowledge-base-web-services, access on January 04, 2024)

Creating a Webservice application

Web service applications are created in genio by selection one of the following target platforms:

  • WCF - Services based on Windows Communication Foundation. The default configuration is SOAP but there are many other possible bindings for TCP, message queueing, etc
  • REST (Recommended) - REST services follow a strict stateless OpenAPI standard of integration. They are lightweight, high performance, scalable service, specialized for http access web environments.

To setup the generation you need to create an application in the client definition with one of the above targets. Then you need to add at least one module that will represent all the interfaces that you wish to make available in the service.

To compose complex services, use multiple modules in the same application. To split up into different deployable services, use multiple applications each with a different module.

Providing query methods

Methods to query a given table are generated for each list you add in the menu tree. The columns of this list will be the fields that will be returned by the method.

Fields like the primary key are automatically added, they do not need to be explicitly declared in the list.

The names of the methods and fields of the service will use the respective description you give them in the list. These names must be unique within their scope. Please take care when using Genio defaults infered from the table definition, they are usually repetitive and are not always adequate for API service names.

The list method generated will provide parameters to sort, filter and page the result set.

Here is an example of the definition of a simple webservice to give access to a Entity table definition

Providing CRUD methods

To provide methods to perform CRUD (Create, Retrieve, Update, Delete) operations you'll have to provide a form in the menu tree. Each form acessible will generate those 4 methods. Forms accessible by the form will also generate methods, so take care with definition of support forms in Lookups.

The form fields and their desciptions will determine the fields and values manipulated by the methods.

The provided CRUD operations will fullfill all the modeled business rules like Not null, Write conditions and formulas.

Composite methods

Some entities are closely related and is expected to be able to change them together. To create composite methods add a Table List to a form with the entity you want to composite.

Genio will generate aditional composite methods for any form that contains at least one Table List that allows the entire set of records to be retreived or updated in one single service method call.

REST

REST services are generated as a Dotnet AspNet WebApi layer over the business core. This layer provides the Http endpoint for the service methods and a Swagger UI documentation site containing the OpenApi specification of the service.

Menu lists will generate each a method of this type:

list example

Forms will each generate the following methods:

form example

For each Table list the following composite methods will be added:

composite example

Binary files

Binary file operations are separated into different method calls specialized for large uploads and downloads. Fields that contain Image or Document type field will instead return a ticket encoded value.

This value can then be used in the GET and POST methods of Resources/file endpoint to respectively Download and Upload those files.

Authentication

Authentication is handled by the Auth/Login method that will return a token that needs to be included in the Http Authentication header with value Bearer <token>.

The token can be requested for varying timeouts up to a maximum. If a client needs to keep calling methods past that time they can either authenticate again ou perform a lightweight token refreh with the Auth/Refresh method.

Configuration for REST services relies on 3 main properties in Webadmin:

  • RESTSECRET - To define the private key seed to use for the tokens.
  • RESTISSUER - Unique uri for this service to prevent token exchange.
  • RESTMAXTIME - To configure the maximum token timeout allowed (in minutes).

More security considerations regarding REST service integration are discusses in the Architecture section.

WCF

The signature for the method generated by this list:

    [OperationContract]
        [WebInvoke(BodyStyle = WebMessageBodyStyle.WrappedRequest,
          RequestFormat = WebMessageFormat.Json,
          ResponseFormat = WebMessageFormat.Json,
          UriTemplate = "DBEditSelectSeveralEntities")]
        DBEditResponseSeveralEntities DBEditSelectSeveralEntities(Authentication authentication, LogicalCondition condition, Paging paging, Order order);

The the signature for method generated for the update operation:

        [OperationContract]
        [WebInvoke(BodyStyle = WebMessageBodyStyle.WrappedRequest,
          RequestFormat = WebMessageFormat.Json,
          ResponseFormat = WebMessageFormat.Json,
          UriTemplate = "FormUpdateCompany")]
        Response FormUpdateCompany(Authentication authentication, FormRecordCompany record);