SpaceDeck – Services

This part of the system allows you to create and test queries using JDBCClosed Java DataBase Connectivity. This is an application programming interface (API) for the Java programming language, which defines how a client may access a database. v3 format to create and execute SQL-99 compliant low code data micro-services. Create a service by optionally defining parameters will that will be supplied on invocation of the exposed RESTClosed REpresentational State Transfer. Application Programming Interface An API, or application programming interface, is a set of rules that define how applications or devices can connect to and communicate with each other. A REST API is an API that conforms to the design principles of the REST, or representational state transfer architectural style. endpoint of that service. These services are used in client services, which are applications that interact with Spaces.

Refer to the deploying services page for information about Service Creator which is the service driving service creation and management.

Security Roles & Permissions

  • Security Roles and Permissions:

    • Deploy/Undeploy actions will require special permission as backend calls are made for deploy and undeploy. In order to deploy or undeploy a service the user will require Manage Service permission. Refer to Security Overview for more details.

    • Create/Delete does not require special permissions as they are currently stored only on the UI server side and which does not contain privileges validation.

Service Main Page

If there are no services currently defined, the Service screen will appear like this:

Services Fields

  • SERVICE NAME – The name of the service.

    The Service name must be in lower case and can contain numbers and one hyphen (-).

  • STATUS – The status of the service:

    • Undeployed - A service that has been created, deployed and is now undeployed. It can also be edited in this state.

    • Deployed - Ready for external execution.

    • Created - A service that has been created but not yet deployed and can still be edited.

  • SPACE NAME – The name of the space to which the service is associated.

  • SWAGGER LINK - The link to use in Swagger UIClosed Swagger UI allows development team to visualize and interact with the API's resources without having any of the implementation logic in place.. For more details, refer to Service Execution through Swagger UI.

  • DESCRIPTION – a free-format description of the service

  • REPLICAS (ACTUAL/PLANNED) – The amount of running replicas vs. requested replicas. If it is a large service, it is recommended to define more than 1 so it can be balanced over multiple instances.

Create a New Service

From the main screen, click Create New Service +

The following configuration screen is displayed. The fields outlined in red are mandatory.

Services Configuration Parameters

  1. (Source drop-down list) – Select which GigaSpaces SpaceClosed Where GigaSpaces data is stored. It is the logical cache that holds data objects in memory and might also hold them in layered in tiering. Data is hosted from multiple SoRs, consolidated as a unified data model. object the service should be executed against. If there is more than one Source, then the specific source will have to be defined. If there is just one Source, this is defined automatically.

  2. Service Name - Provide a unique name for the new service.

    Only lowercase and numbers can be used including one hyphen and it has to start and end with a letter.

  3. Replicas - The number of replicas being used.

  4. Description: Write a short description of the service being created.

  5. (Body of the service) – Create a SQL-99 compliant service. Initially there is an example query service displayed in gray, As soon as you click on that area, it is replaced by a blank screen ready for you to create your service. The results of the example service are also displayed (in our example, these are SAMPLE_FIELD_1, SAMPLE_FIELD_2).

  6. Retrieve first – limit the query response to the desired number of rows. A maximum of 10,000 rows can be retrieved.

  7. Run Query -Click to test the query. The query results will be displayed. If there is a problem with the query a Query validation failed error will be displayed at the bottom of the screen, like this:

  8. Create Service - Click to create the service. It will now be displayed on the main screen with the status Created:

  9. Saved Queries - A list of previously saved queries.

  10. Save Query - Save the query which will then be accessible via the Saved Queries drop-down.

Create Service Example

  1. In the Configuration tab, create the query for the service. For requesting results pagination refer to Support for Service Results Pagination.

  2. Click Run Query to test it.

  3. The results are displayed.

  4. The results can be exported to a .csv file.

  5. Save the query.

  6. Deploy or Undeploy the query as a service. Depending on whether the status is Created or Deployed.

  7. If the service is created, use this kebab menu to either Deploy or Delete the service. If the service is deployed, use this kebab menu to either Download Logs, Undeploy Service or Go to API Docs.

Support for Service Results Pagination

In some cases, services can return multiple rows from a Space. If the goal is to display the data in some web application, the pagination approach is often used. This avoids all the data being displayed on one long page, which is not practical. Instead the data is divided into smaller pages.

It is often required that services support this approach also on the back-end side because it is not practical to bring large amounts of data to the front-end only to then divide it into smaller pages. In many cases a developer will prefer to fetch relevant amounts of information for a given page from the front end.

Pagination is now possible using a combination of service parameters together with LIMIT and OFFSET and ORDER BY SQL keywords.

LIMIT defines the page size. OFFSET defines the first row for a given page.  For OFFSET, a basic calculation is performed of page number minus one multiplied by page size. This will results in a request that returns data that is relevant for a given page instead of returned all the data.

When using LIMIT, it is important to use an ORDER BY clause that constrains the result rows into a unique order. Otherwise you will get an unpredictable subset of the query's rows.

Example (assuming ID is in the Person table):

Deployed Service

  1. Once the service is deployed, there in a option from this screen to Undeploy the service.

  2. Once deployed, use this kebab menu to either Download Logs, Undeploy Service or Go to API Docs.

    For more details about Logs, refer to Change Log Level Dynamically.

    For more details about API Docs, refer to API Docs: Registering a Query Service to an API GW.

Service Main Page with Services Defined

The main Services screen displays a list of services.  For our example, three services have been created all with different statuses.

  1. SERVICE NAME – Click this to get to the configuration screen.

  2. STATUS – The status of defined services.

    • Deployed - A service ready for external execution.

    • Undeployed- A service that has been deployed or has been undeployed for editing purposes.

    • Created - A service that has not been deployed and can still be edited.

  3. Once deployed, use this kebab menu to either Download Logs, Undeploy Service or Go to API Docs.

  • If the service is in an Undeployed or Created state, the kebab menu options will be Deploy Service or Delete Service.

Service Monitoring

For each deployed service, there is monitoring supplied through SpaceDeckClosed GigaSpaces intuitive, streamlined user interface to set up, manage and control their environment. Using SpaceDeck, users can define the tools to bring legacy System of Record (SoR) databases into the in-memory data grid that is the core of the GigaSpaces system.. From the Services main page, click on a service and once in the next screen, click the Monitoring tab:

Monitoring Types

  • Execution response trend over time - Monitored by Request Succeeded, Bad Request and Server Error

  • New execution response - Different view of Request Succeeded, Bad Request and Server Error

  • Execution latency in milliseconds - Displaying the service execution latency in milliseconds

Service Execution through Swagger UI

There are two options to execute a service query. Either through the service URL endpoint or using Swagger UI (in the case where the SQL query has parameter placeholders there will be values to fill in.  If not, there will be no parameter values listed). Through Swagger UI, a value must be entered for each parameter. In the case where there are no parameters, there will be no option given to enter parameters. In the example below, the Parameters and values supplied are id2 and id1:

Execution Results:

 

API Docs: Registering a Query Service to an API GW

Only once a service has been deployed and the Swagger link is accessible (responds with 200 status) will the URL of the API Docs be available.

  1. Through the kebab menu there is an option to Go to API Docs. This will open a JSON in Open API format which is used to register to an API Gateway.

  2. Copy the contents of that page.

  3. For our example we are using the AWS GW. Open this API GW and click Create API:

  4. Select REST APIClosed REpresentational State Transfer. Application Programming Interface An API, or application programming interface, is a set of rules that define how applications or devices can connect to and communicate with each other. A REST API is an API that conforms to the design principles of the REST, or representational state transfer architectural style. and click import:

  5. Select the option of Import from Swagger or Open API 3 and paste the output of the API Docs (copied previously). Then click Import:

  6. Under the single endpoint of the query, configure the following parameters:

  • Integration type: HTTP

  • Use Proxy Integration: Check this option

  • Method: GET

  • Endpoint URL:The endpoint of the service. In the example, it is the URI of the service without any additional query parameters.

  • Use Default Timeout: Check this option

Logs and Changing the Log Level Dynamically

Once a service has been undeployed the log is erased. Once the service is stopped and started the log level resets as there is a new internal ID created for the service. If there is more than one replica defined, they are contained in the single .zip file that is produced.  

The default log level is configured to "INFO". Currently the ability to change the log level is not available through SpaceDeck. However, this can be achieved through CURL or using Postman.

Through Postman:

  1. In the service's endpoint go the relative path: /actuator/loggers/com.gigaspaces.mcs.service.query.

  2. Configure the request body {"configuredLevel": "DEBUG"}.

In the example below the name of the service is "get-people-by-id-range":

Through CURL

curl -X POST -H "Content-Type: application/json" -d '{"configuredLevel": "DEBUG"}' http://<IP of cluster>/api/get-people-by-id-range/actuator/loggers/com.gigaspaces.mcs.service.query