Basic Notions

TS Enterprise WebApi is an ecosystem of web services that follows REST architectural principles and is based on a few simple general rules.

Below is an overview of the fundamental principles of REST architecture, along with some details on how these principles are applied in Enterprise.
Refer to the technical training course "ENT355 - TS Enterprise - DOMAIN MODEL AND WEB API DEVELOPMENT" included in the education calendar for further insights.

Definition of resources in the form of URLs

Based on the HTTP protocol.

In TSE WebAPI, it is possible to query the service through simple HTTP requests, using clients based on any technology: web browsers, C# clients, Java, Python, JavaScript, Windows or Linux operating systems.

Each URL uniquely defines access to a data resource.

URLs identify the type of data being operated on. Unless otherwise specified during configuration, TSE WebAPIs respond to the local address:

http://localhost:9080/api/v1/production/{module}/{resource}

On the consumer side, the APIs are made available through the APIGateway routing services, and we will therefore refer to the URL for each resource:

https://webapi_base_url/v1/production/{module}/{resource}

Each resource is organized by module. Explicitly indicating the module allows the request to be routed to the correct reference service.

For example, assuming the web API service is listening at the "root" URL http://localhost/api/v1/scope/, where "scope" is the name of the working environment (see the next section), the different functionalities exposed by the service are exposed as URLs based on this root.

Here are some examples:

• http://localhost/api/v1/scope/MG/documento/ resource URL for ALL possible operations on documents
• http://localhost/api/v1/scope/CO/CompanyCO/ resource URL for ALL possible operations on companies
• http://localhost/api/v1/scope/CO/GeneralMasterDataCO/ resource URL for ALL possible operations on general master data

All root-type entities can be exposed as resources in the WebAPI service simply by compiling the relevant metadata for Controller, Manager, and DTO (see details below).

Naming conventions

By convention, each resource defaults to the name of the entity itself, in English, unless otherwise decided during development; for example, in the case of the "DocumentoTestataMG" entity, it was decided during development to expose this resource not using the default value "DocumentoTestataMG" but using the value "documento".

Environments as a resource

Speaking of resources, the first and most important is the working application environment, i.e., the part of the URL to the right of the "root" http://localhost/api/v1/, for example: "scope" in http://localhost/api/v1/scope/.

The application environment identifies a working area associated with a database: the resources of each environment, for example, "gammanext/documenti" and "servicenext/documenti," therefore have the same structure but represent different data.

Authentication

Refer to the AUTHENTICATION section for information on how to access the available environments.

Respect for semantics and HTTP commands

Once a resource is defined in the form of a URL, the possible operations on that resource are linked to the resource's URL and the HTTP methods used by the caller.

For example:

• GET: retrieves the resource, i.e., the DTO configured with the key specified in the URL
• PUT: modifies the resource with the key specified in the URL; the body will contain the same DTO returned by the GET, with the appropriate properties modified
• DELETE: deletes the resource with the key specified in the URL
• POST: creates a new resource element and returns the corresponding DTO
• PATCH: modifies only a specific property of the DTO; there is no need to send the entire DTO in the body, only the properties to be updated. If you want to modify the properties of an element of an internally related collection, you must also specify the keys of the related entity, in addition to the properties to be modified.

When we talk about "retrieve," "modify," "delete," and "create," we mean the corresponding operations implemented by the specific Biz managing the aggregate. Each operation offered by Enterprise WebAPI should be considered as "exposure to external clients via REST services" of business operations, except in special cases.

NOTE: Note the different semantics of the POST operation, which does not require specifying the ID in the URL, unlike the other GET, PUT, and DELETE operations. In fact, POST is used for all operations that do not work directly on an existing resource, such as:

• Search: free search (by text value or specific filter) on the resource
• Validate: validation of a resource (i.e., the DTO representing the aggregate entity) that may or may not already exist
• ValidateProperties: validation of one or more properties of a resource, whether existing or not
• Other: other operations, of any type, implemented for specific cases (e.g., Approve or Reject RDA)

These operations also effectively call the corresponding operations present in the standard Biz, i.e., the Search and Validate operations, or those created by the programmer (in the case of "Other").

warning

The HTTP methods HEAD, CONNECT, OPTIONS, TRACE are not used.

Self-descriptive resources

As mentioned earlier, every read/write operation on a resource operates on a DTO, i.e., a Data Transfer Object specifically defined to decouple the representation of the resource exposed to external clients from the entity defined at the Biz level.

The serialization format of the DTO to be used as an exchange can be defined by the client querying the service by adding the HTTP header "Accept" to the request, and two values are supported:

• application/json: JSON serialization; this is the default value used if the "Accept" header is not specified by the caller
• application/xml: XML serialization

The service response contains, in its "Content-Type" header, the serialization format, i.e.:

• application/json: JSON serialization; this is the default value used if the "Accept" header is not specified by the caller
• application/xml: XML serialization
• text/html: in case of error messages and in operations that return textual content, such as "Validate" and "ValidateProperties"

encoding

The encoding used (usually utf-8) is also returned, for example:

REQUEST  => Accept: application/json
RESPONSE => Content-Type: application/json; charset: utf-8

Localization

Multilingual support is also managed via HTTP headers; specifically, by specifying the "Accept-Language" header with a specific value in RFC 4646 standard, the application session is initialized using the globalization information specified.

REQUEST  => Accept-Language: en-US
RESPONSE => Content-Language: en-US

Language

By default, i.e., if "Accept-Language" is not specified, the session is initialized with the globalization information for the Italian language "it-IT."

Stateless protocol

In compliance with the HTTP protocol, every request from clients is processed in a completely stateless manner, meaning that any request has no relation to previous requests made by the same caller. A single request must therefore contain ALL the information necessary to perform the desired operation, starting with authentication information and user session creation.

In the case of a GET request, the following must be specified:

• Authentication type: mandatory
• Credentials: mandatory, depending on the authentication system used
• Header "Authorization-Scope": mandatory, header for accessing the requested environment
• Query parameter "user": optional, in case you want to perform the operation "impersonating" an application user different from the one mapped at the user configuration level of the service; the parameter specification follows standard specifications, e.g., ?user=guest
• Query parameter "company": mandatory for company-dependent resources; the parameter specification follows standard specifications, e.g., ?company=1

Security and idempotence

A method is defined as SAFE when the corresponding request does not alter the state of the resource itself or any related resources: we therefore speak more generally of SAFE methods as they do not alter the server state.

GET methods are SAFE, so they can be called countless times without worrying about "side effects," while PUT and DELETE methods are not SAFE by definition: each PUT modifies the corresponding resource (unless the same representation is always passed, but even in this case, some auto-generated fields may differ), while DELETE removes the resource, making it no longer available.

The POST method has behavior dependent on the type of operation implemented; the POST method is not SAFE for the "Create" operation, while POST methods for "Search," "Validate," and "ValidateProperties" operations are SAFE. Custom operations may be SAFE or not, depending on the implemented operation; see the POST operations section for more details.

A method is defined as IDEMPOTENT if there is no difference in the server state between executing a single request or N multiple requests of the same identical request.

The GET method is therefore idempotent because, apart from external processes modifying the data being read, the server state remains unchanged regardless of the number of requests made (logging and internal processes such as counters or others are not considered). PUT and DELETE methods are also idempotent because the server state is altered only on the first deletion or modification request, while subsequent ones do not (or should not) modify the server state.

The POST method is not generally considered idempotent: it is not for the "Create" operation (each request creates a distinct resource), while it is for the "Search," "Validate," and "ValidateProperties" operations.

General schema

For each resource exposed by the service, the framework provides a series of operations for CRUD, search, validation, and data lookups.

The base URL for all calls is as follows: http|https://{server}[:{port}]/api/{version}/production

• {version}: v1
• production: abbreviation corresponding to a configured environment (see CONFIGURATION)

PORT

The port parameter is optional; if not specified, port 80 is used by default for HTTP requests or port 443 for HTTPS requests.

Application user and working company

In every request to the WebApi service, you can specify the parameters

• user: application user name
• company: working company, mandatory parameter in functional calls

These parameters should be added to the URL with standard syntax, as follows:

GET: http://{server}:{port}/api/v1/production/{module}/{resource}/0?user=TeamSa&company=1

If not specified, the values used will be those specified during the configuration of the user used for authentication to the service.