001/**
002 * Copyright (C) 2006-2025 Talend Inc. - www.talend.com
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016package org.talend.sdk.component.server.api;
017
018import static javax.ws.rs.core.MediaType.APPLICATION_JSON;
019import static org.eclipse.microprofile.openapi.annotations.enums.ParameterIn.QUERY;
020import static org.eclipse.microprofile.openapi.annotations.enums.SchemaType.OBJECT;
021import static org.eclipse.microprofile.openapi.annotations.enums.SchemaType.STRING;
022
023import java.util.Map;
024import java.util.concurrent.CompletionStage;
025
026import javax.ws.rs.Consumes;
027import javax.ws.rs.DefaultValue;
028import javax.ws.rs.GET;
029import javax.ws.rs.POST;
030import javax.ws.rs.Path;
031import javax.ws.rs.Produces;
032import javax.ws.rs.QueryParam;
033import javax.ws.rs.core.Response;
034
035import org.eclipse.microprofile.openapi.annotations.Operation;
036import org.eclipse.microprofile.openapi.annotations.media.Content;
037import org.eclipse.microprofile.openapi.annotations.media.Schema;
038import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
039import org.eclipse.microprofile.openapi.annotations.parameters.RequestBody;
040import org.eclipse.microprofile.openapi.annotations.responses.APIResponse;
041import org.eclipse.microprofile.openapi.annotations.tags.Tag;
042import org.talend.sdk.component.server.front.model.ActionList;
043import org.talend.sdk.component.server.front.model.error.ErrorPayload;
044
045@Path("action")
046@Consumes(APPLICATION_JSON)
047@Produces(APPLICATION_JSON)
048@Tag(name = "Action", description = "Endpoints related to callbacks/triggers execution.")
049public interface ActionResource {
050
051    @POST
052    @Path("execute")
053    @Operation(
054            description = "This endpoint will execute any UI action and serialize the response as a JSON (pojo model). "
055                    + "It takes as input the family, type and name of the related action to identify it and its configuration "
056                    + "as a flat key value set using the same kind of mapping than for components (option path as key).")
057    @APIResponse(responseCode = "200",
058            description = "The action payload serialized in JSON.",
059            content = @Content(mediaType = APPLICATION_JSON))
060    @APIResponse(responseCode = "400",
061            description = "If the action is not set, payload will be an ErrorPayload with the code ACTION_MISSING.",
062            content = @Content(mediaType = APPLICATION_JSON,
063                    schema = @Schema(type = OBJECT, implementation = ErrorPayload.class)))
064    @APIResponse(responseCode = "404",
065            description = "If the action can't be found, payload will be an ErrorPayload with the code ACTION_MISSING.",
066            content = @Content(mediaType = APPLICATION_JSON,
067                    schema = @Schema(type = OBJECT, implementation = ErrorPayload.class)))
068    @APIResponse(responseCode = "520",
069            description = "If the action execution failed, payload will be an ErrorPayload with the code ACTION_ERROR.",
070            content = @Content(mediaType = APPLICATION_JSON,
071                    schema = @Schema(type = OBJECT, implementation = ErrorPayload.class)))
072    CompletionStage<Response> execute(
073            @QueryParam("family") @Parameter(name = "family", required = true, in = QUERY,
074                    description = "Component family.") String family,
075            @QueryParam("type") @Parameter(name = "type", required = true, in = QUERY,
076                    description = "Type of action.") String type,
077            @QueryParam("action") @Parameter(name = "action", required = true, in = QUERY,
078                    description = "Action name.") String action,
079            @QueryParam("lang") @DefaultValue("en") @Parameter(name = "lang", in = QUERY,
080                    description = "Requested language (as in a Locale) if supported by the action.",
081                    schema = @Schema(defaultValue = "en", type = STRING)) String lang,
082            @RequestBody(description = "Action parameters in key/value flat json form.", required = true,
083                    content = @Content(mediaType = APPLICATION_JSON,
084                            schema = @Schema(type = OBJECT))) Map<String, String> params);
085
086    @GET
087    @Path("index")
088    @Operation(operationId = "getActionIndex",
089            description = "This endpoint returns the list of available actions for a certain family and potentially filters the "
090                    + "output limiting it to some families and types of actions.")
091    @APIResponse(responseCode = "200",
092            description = "The action index.",
093            content = @Content(mediaType = APPLICATION_JSON))
094    ActionList getIndex(
095            @QueryParam("type") @Parameter(name = "type", in = QUERY,
096                    description = "Filter the response by type." +
097                            "Repeat this parameter to request more than one type.") String[] types,
098            @QueryParam("family") @Parameter(name = "family", in = QUERY,
099                    description = "Filter the response by family." +
100                            "Repeat this parameter to request more than one family.") String[] families,
101            @QueryParam("language") @Parameter(name = "language",
102                    description = "Response language in i18n format.", in = QUERY,
103                    schema = @Schema(defaultValue = "en", type = STRING)) @DefaultValue("en") String language);
104}