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.PATH;
020import static org.eclipse.microprofile.openapi.annotations.enums.ParameterIn.QUERY;
021import static org.eclipse.microprofile.openapi.annotations.enums.SchemaType.BOOLEAN;
022import static org.eclipse.microprofile.openapi.annotations.enums.SchemaType.OBJECT;
023import static org.eclipse.microprofile.openapi.annotations.enums.SchemaType.STRING;
024
025import java.util.Map;
026
027import javax.ws.rs.Consumes;
028import javax.ws.rs.DefaultValue;
029import javax.ws.rs.GET;
030import javax.ws.rs.POST;
031import javax.ws.rs.Path;
032import javax.ws.rs.PathParam;
033import javax.ws.rs.Produces;
034import javax.ws.rs.QueryParam;
035
036import org.eclipse.microprofile.openapi.annotations.Operation;
037import org.eclipse.microprofile.openapi.annotations.media.Content;
038import org.eclipse.microprofile.openapi.annotations.media.Schema;
039import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
040import org.eclipse.microprofile.openapi.annotations.parameters.RequestBody;
041import org.eclipse.microprofile.openapi.annotations.responses.APIResponse;
042import org.eclipse.microprofile.openapi.annotations.tags.Tag;
043import org.talend.sdk.component.server.front.model.ConfigTypeNodes;
044import org.talend.sdk.component.server.front.model.error.ErrorPayload;
045
046@Path("configurationtype")
047@Consumes(APPLICATION_JSON)
048@Produces(APPLICATION_JSON)
049@Tag(name = "Configuration Type",
050        description = "Endpoints related to configuration types (reusable configuration) metadata access.")
051public interface ConfigurationTypeResource {
052
053    @GET
054    @Path("index")
055    @Operation(description = "Returns all available configuration type - storable models. "
056            + "Note that the lightPayload flag allows to load all of them at once when you eagerly need "
057            + " to create a client model for all configurations.")
058    @APIResponse(responseCode = "200",
059            description = "List of available and storable configurations (datastore, dataset, ...).",
060            content = @Content(mediaType = APPLICATION_JSON))
061    ConfigTypeNodes getRepositoryModel(
062            @QueryParam("language") @DefaultValue("en") @Parameter(name = "language",
063                    description = "Response language in i18n format.", in = QUERY,
064                    schema = @Schema(type = STRING, defaultValue = "en")) String language,
065            @QueryParam("lightPayload") @DefaultValue("true") @Parameter(name = "lightPayload",
066                    description = "Should the payload skip the forms and actions associated to the configuration." +
067                            "Default value is `true`.",
068                    in = QUERY, schema = @Schema(type = BOOLEAN, defaultValue = "true")) boolean lightPayload,
069            @QueryParam("q") @Parameter(name = "q",
070                    description = "Query in simple query language to filter configurations. "
071                            + "It provides access to the configuration `type`, `name`, `type` and "
072                            + "first configuration property `metadata`. "
073                            + "See component index endpoint for a syntax example.",
074                    in = QUERY, schema = @Schema(type = STRING)) String query);
075
076    @GET
077    @Path("details")
078    @Operation(operationId = "getConfigurationDetail",
079            description = "Returns the set of metadata about one or multiples configuration identified by their 'id'.")
080    @APIResponse(responseCode = "200",
081            description = "List of details for the requested configuration.",
082            content = @Content(mediaType = APPLICATION_JSON))
083    ConfigTypeNodes getDetail(
084            @QueryParam("language") @DefaultValue("en") @Parameter(name = "language",
085                    description = "Response language in i18n format.",
086                    in = QUERY,
087                    schema = @Schema(type = STRING, defaultValue = "en")) String language,
088            @QueryParam("identifiers") @Parameter(name = "identifiers",
089                    description = "The identifier id to request. " +
090                            "Repeat this parameter to request more than one element.",
091                    in = QUERY) String[] ids);
092
093    @POST
094    @Path("migrate/{id}/{configurationVersion}")
095    @Operation(operationId = "migrateConfiguration",
096            description = "Allows to migrate a configuration without calling any component execution.")
097    @APIResponse(responseCode = "200",
098            description = "New values for that configuration (or the same if no migration was needed).",
099            content = @Content(mediaType = APPLICATION_JSON))
100    @APIResponse(responseCode = "404",
101            description = "If the configuration is missing, payload will be an ErrorPayload with the code CONFIGURATION_MISSING.",
102            content = @Content(mediaType = APPLICATION_JSON,
103                    schema = @Schema(type = OBJECT, implementation = ErrorPayload.class)))
104    @APIResponse(responseCode = "520",
105            description = "An unexpected error occurred during migration, payload will be an ErrorPayload with the code UNEXPECTED.",
106            content = @Content(mediaType = APPLICATION_JSON))
107    Map<String, String> migrate(
108            @PathParam("id") @Parameter(name = "id",
109                    description = "The configuration identifier.",
110                    in = PATH) String id,
111            @PathParam("configurationVersion") @Parameter(name = "configurationVersion",
112                    description = "The configuration version you send in provided body.",
113                    in = PATH) int version,
114            @RequestBody(
115                    description = "Configuration to migrate in key/value json form.", required = true,
116                    content = @Content(mediaType = APPLICATION_JSON,
117                            schema = @Schema(type = OBJECT))) Map<String, String> config);
118}