HTTP tutorial - REST
An alternative to building a web service is offered by RESTful (Representational State Transfer) API (Application Programming Interface) or WebAPI. The RESTAPI forms the architecture for a uniform interface to systems or programmes in order to transmit or use data via HTTP request in a standardised form.
Stateless client/server communication (always new structure, cloud-capable).
Transmission format: JSON (preferred), HTML, plain text, etc.
Protocol: HTTP with permitted standard methods: GET, PUT, POST, DELETE.
Cacheable data.
Differences in request and response headers with regard to connection information and status codes.
Headers and parameters form important components in the HTTP methods of a RESTful API HTTP request:
Metadata with ID information.
Authorisation.
URI.
Caching.
Cookies, etc.
Note: You can find a good overview of the REST topic at Microsoft, for example.
Unfortunately, in contrast to SOAP, there is no standardisation instance here. Various approaches have been established for SOAP with the interface description WSDL, e.g. Swagger (formerly OpenAPI) or RAML.
RESTful API
You usually need a simple profile that implements the requirement for the interface.
Assuming you want to receive data via the API, it is sufficient to set the POST method in the Input Agent and activate the checkbox Treat as REST interface.
Let's assume you want to use HTTP methods to use a RESTful API, for example, to add a new customer to a customer master record (PUT), to display the customer data (GET/POST), to update the master records (PATCH) or to delete a master record (DELETE). In the first case, no data record is available yet, but in the other cases, a concrete object, e.g. with the help of a parameter for a variable customer number, can be given directly in the URL and retrieved via API.
GET https://<Server>/dw/Request/showCustomer/<USERID>
Alternatively with query parameter
GET https://<Server>/dw/Request/showCustomer/?USERID=4711
In this case, we recommend giving the value showCustomer to the "URL address prefix" in the newly created REST profile. If you now make the HTTP call in a browser, this will lead to success. Via the system variable MSG_CALL_HTTP_PATH_DATA, you have the possibility in phase 3 to read the additional parts of the request and to start them, for example, via a database query against the value 4711. You can then return the result to the client as JSON.
Note: From time to time, REST APIs expect special parameters, such as the Accept header, which tells the server which output the client accepts from the server. Here you would do well to use the value "*/*".
Swagger and RAML
Unlike SOAP with WSDL, there is no uniform interface description, but two formats have crystallised here.
For RAML, you can generate an interface description via the profile export.
Such an interface file is used to generate a mapping structure. A "structure import" can be carried out within the Main settings or in phase 3.
The Swagger format (formerly OpenAPI) is widely used. A Swagger file can be used to create source or target structures. To do this, download the JSON file via the corresponding menu of the source or target structure and the option Analyze file. If the analysis is successful, the dialogue offers you the possibility to apply the Swagger import.
The structures defined in Swagger are then created as substructures and can be adapted manually. For further information, please also refer to the documentation.