Basic Operations
TS Enterprise Smart WebApi Services 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.
Resource Definition as URLs
Based on the HTTP protocol.
You can query the service through simple HTTP requests using clients based on any technology: web browsers, C#, Java, Python, JavaScript clients, Windows or Linux operating systems.
Each URL uniquely defines access to a data resource.
URLs identify the type of data being operated on:
https://tse.smart-api.teamsystem.cloud/api/{product}/{version}/company/{companyId}/customer/{customerId}
On the consumer side, the APIs are provided through a single endpoint, and routing to the corresponding resource is automatic.
Each resource is organized by module. Explicitly indicating the module allows routing the request to the correct reference service.
For example, assuming the Web API service is listening at the “root” URL:
https://tse.smart-api.teamsystem.cloud/api/{product}/{version}/company/{companyId}
The different functionalities exposed by the service are presented as URLs based on this root.
Here are some examples:
/documentResource URL for ALL possible operations on documents.company/{companyId}/Resource URL for ALL possible operations on companies and their sub-entities./company/{companyId}/customerResource URL for ALL possible operations on customers.
By convention, each resource defaults to the name of the entity itself, in English.
See the AUTHENTICATION section for information on how to access the available environments.
Compliance with HTTP Semantics and Commands
Once a resource is defined as 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:: updates 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 element of the resource and returns the corresponding DTO.
- PATCH:: updates only a specific property of the DTO; therefore, there is no need to send the entire DTO in the body, only the property or properties to be updated. If you want to modify the properties of an element in an internally related collection, you must also specify the keys of the related entity, in addition to the properties you intend to modify.
When we talk about “retrieve,” “update,” “delete,” and “create,” we refer to the corresponding operations implemented by the specific business logic that manages the aggregate. Each operation offered by Enterprise WebAPI should be considered as an exposure to external clients via REST services of business operations, except for special cases.
NOTE: Notice the different semantics of the POST operation, which does not require specifying the ID in the URL, unlike the other operations (GET, PUT, DELETE). In fact, POST is used for all operations that do not work directly on an existing resource, such as:
HTTP methods HEAD, CONNECT, OPTIONS, and TRACE are not used.
Self-Descriptive Resources
As mentioned earlier, every read/write operation on a resource works on a DTO (Data Transfer Object), specifically defined to decouple the representation of the resource exposed to external clients.
The serialization format of the DTO used for data exchange can be defined by the client querying the service by adding the HTTP header Accept to the request. Two values are supported:
application/json: JSON serialization; this is the default value used if the Accept header is not specified by the caller.
The service response contains, in its Content-Type header, the serialization format, which is:
application/json: JSON serialization; this is the default value used if the Accept header was not specified by the caller.
The encoding used (usually UTF-8) is also returned, for example:
REQUEST => Accept: application/json
RESPONSE => Content-Type: application/json; charset: utf-8
Localition
Multilingual support is also managed via HTTP headers. Specifically, by specifying the Accept-Language header with a value in RFC 4646 standard, the application session is initialized using the specified globalization settings.
REQUEST => Accept-Language: en-US
RESPONSE => Content-Language: en-US
Stateless Protocol
In compliance with the HTTP protocol, every request coming from clients is processed in a completely stateless manner. This means 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 execute the desired operation, starting from authentication details and user session creation.
For a GET request, you must specify:
- Authentication type: mandatory
- Credentials: mandatory
Security and Idempotence
A method is defined as SAFE when its request does not alter the state of the resource itself or any related resources. In general, SAFE methods do not change the server state.
- GET methods are SAFE, meaning they can be called repeatedly without worrying about side effects.
- PUT and DELETE methods are not SAFE by definition:
- Each PUT modifies the corresponding resource (unless the same representation is always sent, but even then, some auto-generated fields may differ).
- DELETE removes the resource, making it unavailable.
- POST behavior depends on the type of operation implemented; generally, POST is not SAFE.
A method is defined as IDEMPOTENT when there is no difference in the server state between executing a single request or multiple identical requests.
GET is idempotent because, aside from external processes modifying the data, the server state remains unchanged regardless of the number of requests (logging and internal counters are not considered). PUT and DELETE are also idempotent because the server state changes only on the first modification or deletion request; subsequent identical requests do not (or should not) alter the state. POST is generally not idempotent, especially for “Create” operations (each request creates a distinct resource).
General Schema
For each resource exposed by the service, the framework provides a set of operations for CRUD.
The base URL for all calls is: https://tse.smart-api.teamsystem.cloud
{product}: abbreviation corresponding to the target product{version}: v1, version of the services
The port parameter is optional. To access the services, use HTTPS, which corresponds to port 443.