redback-integrations/redback-rest/redback-rest-api/src/main/java/org/apache/archiva/redback/rest/api/services/v2/UserService.java

package org.apache.archiva.redback.rest.api.services.v2;

/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */

import io.swagger.v3.oas.annotations.headers.Header;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.apache.archiva.redback.authorization.RedbackAuthorization;
import org.apache.archiva.redback.integration.security.role.RedbackRoleConstants;
import org.apache.archiva.redback.rest.api.model.ActionStatus;
import org.apache.archiva.redback.rest.api.model.v2.AvailabilityStatus;
import org.apache.archiva.redback.rest.api.model.Operation;
import org.apache.archiva.redback.rest.api.model.v2.PagedResult;
import org.apache.archiva.redback.rest.api.model.PasswordStatus;
import org.apache.archiva.redback.rest.api.model.Permission;
import org.apache.archiva.redback.rest.api.model.v2.PingResult;
import org.apache.archiva.redback.rest.api.model.ResetPasswordRequest;
import org.apache.archiva.redback.rest.api.model.v2.RegistrationKey;
import org.apache.archiva.redback.rest.api.model.v2.User;
import org.apache.archiva.redback.rest.api.model.v2.UserRegistrationRequest;
import org.apache.archiva.redback.rest.api.model.VerificationStatus;
import org.apache.archiva.redback.rest.api.services.RedbackServiceException;

import javax.ws.rs.Consumes;
import javax.ws.rs.DELETE;
import javax.ws.rs.DefaultValue;
import javax.ws.rs.GET;
import javax.ws.rs.POST;
import javax.ws.rs.PUT;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
import javax.ws.rs.QueryParam;
import javax.ws.rs.core.MediaType;
import java.util.Collection;

import static org.apache.archiva.redback.rest.api.Constants.DEFAULT_PAGE_LIMIT;

@Path( "/users" )
@Tag(name = "v2")
@Tag(name = "v2/Users")
@SecurityRequirement(name = "BearerAuth")
public interface UserService
{
    @Path( "{userId}" )
    @GET
    @Produces( { MediaType.APPLICATION_JSON } )
    @RedbackAuthorization( permissions = RedbackRoleConstants.USER_MANAGEMENT_USER_EDIT_OPERATION )
    User getUser( @PathParam( "userId" ) String userId )
        throws RedbackServiceException;


    @Path( "" )
    @GET
    @Produces( { MediaType.APPLICATION_JSON } )
    @RedbackAuthorization( permissions = RedbackRoleConstants.USER_MANAGEMENT_USER_LIST_OPERATION )
    PagedResult<User> getUsers( @QueryParam( "offset" ) @DefaultValue( "0" ) Integer offset,
                                      @QueryParam( "limit" ) @DefaultValue( value = DEFAULT_PAGE_LIMIT ) Integer limit)
        throws RedbackServiceException;

    @Path( "" )
    @POST
    @Produces( { MediaType.APPLICATION_JSON } )
    @Consumes( { MediaType.APPLICATION_JSON } )
    @RedbackAuthorization( permissions = RedbackRoleConstants.USER_MANAGEMENT_USER_CREATE_OPERATION )
    @io.swagger.v3.oas.annotations.Operation( summary = "Creates a user",
        responses = {
            @ApiResponse( responseCode = "201",
                description = "If user creation was successful",
                headers = {
                    @Header( name="Location", description = "The URL of the created mapping")
                }
            ),
            @ApiResponse( responseCode = "405", description = "Invalid input" ),
            @ApiResponse( responseCode = "303", description = "The user exists already",
                headers = {
                    @Header( name="Location", description = "The URL of existing user")
                }
            )
        }
    )
    User createUser( User user )
        throws RedbackServiceException;


    /**
     * will create admin user only if not exists !! if exists will return false
     */
    @Path( "admin" )
    @POST
    @Produces( { MediaType.APPLICATION_JSON } )
    @Consumes( { MediaType.APPLICATION_JSON } )
    @RedbackAuthorization( noRestriction = true )
    @io.swagger.v3.oas.annotations.Operation( summary = "Creates a user",
        responses = {
            @ApiResponse( responseCode = "201",
                description = "If user creation was successful",
                headers = {
                    @Header( name="Location", description = "The URL of the created mapping")
                }
            ),
            @ApiResponse( responseCode = "405", description = "Invalid input" ),
            @ApiResponse( responseCode = "303", description = "The user exists already",
                headers = {
                    @Header( name="Location", description = "The URL of the existing admin user")
                }
            )
        }
    )
    User createAdminUser( User user )
        throws RedbackServiceException;

    @Path( "admin/status" )
    @GET
    @Produces( { MediaType.APPLICATION_JSON } )
    @RedbackAuthorization( noRestriction = true )
    AvailabilityStatus getAdminStatus()
        throws RedbackServiceException;


    @Path( "{userId}" )
    @DELETE
    @Produces( { MediaType.APPLICATION_JSON } )
    @RedbackAuthorization( permissions = RedbackRoleConstants.USER_MANAGEMENT_USER_DELETE_OPERATION )
    @io.swagger.v3.oas.annotations.Operation( summary = "Creates a user",
        responses = {
            @ApiResponse( responseCode = "200",
                description = "If user deletion was successful"
            ),
            @ApiResponse( responseCode = "404", description = "User does not exist" )
        }
    )
    void deleteUser( @PathParam( "userId" ) String userId )
        throws RedbackServiceException;

    @Path( "{userId}" )
    @PUT
    @Produces( {MediaType.APPLICATION_JSON} )
    @RedbackAuthorization( permissions = RedbackRoleConstants.USER_MANAGEMENT_USER_EDIT_OPERATION )
    @io.swagger.v3.oas.annotations.Operation( summary = "Creates a user",
        responses = {
            @ApiResponse( responseCode = "200",
                description = "If update was successful"
            ),
            @ApiResponse( responseCode = "404", description = "User does not exist" ),
            @ApiResponse( responseCode = "422", description = "Update data was not valid. E.g. password violations." )
        }
    )
    User updateUser( @PathParam( "userId" ) String userId, User user )
        throws RedbackServiceException;

    /**
     */
    @Path( "{userId}/lock" )
    @POST
    @Produces( { MediaType.APPLICATION_JSON } )
    @RedbackAuthorization( permissions = RedbackRoleConstants.USER_MANAGEMENT_USER_EDIT_OPERATION )
    ActionStatus lockUser( @PathParam( "userId" ) String userId )
        throws RedbackServiceException;

    /**
     */
    @Path( "{userId}/unlock" )
    @GET
    @Produces( { MediaType.APPLICATION_JSON } )
    @RedbackAuthorization( permissions = RedbackRoleConstants.USER_MANAGEMENT_USER_EDIT_OPERATION )
    ActionStatus unlockUser( @PathParam( "userId" ) String userId )
        throws RedbackServiceException;


    /**
     */
    @Path( "{userId}/password/status" )
    @GET
    @Produces( { MediaType.APPLICATION_JSON } )
    @RedbackAuthorization( permissions = RedbackRoleConstants.USER_MANAGEMENT_USER_EDIT_OPERATION )
    PasswordStatus getPasswordStatus( @PathParam( "userId" ) String userId )
        throws RedbackServiceException;

    /**
     * update only the current user and this fields: fullname, email, password.
     * The service verifies the current logged user with the one passed in the method
     */
    @Path( "me" )
    @PUT
    @Produces( { MediaType.APPLICATION_JSON } )
    @RedbackAuthorization( noPermission = true )
    ActionStatus updateMe( @PathParam( "userId" ) String userId, User user )
        throws RedbackServiceException;

    @Path( "___ping___" )
    @GET
    @Produces( { MediaType.APPLICATION_JSON } )
    @RedbackAuthorization( noRestriction = true )
    PingResult ping()
        throws RedbackServiceException;

    @Path( "{userId}/cache/clear" )
    @POST
    @Produces( { MediaType.APPLICATION_JSON } )
    @RedbackAuthorization( permissions = RedbackRoleConstants.USER_MANAGEMENT_USER_EDIT_OPERATION )
    ActionStatus removeFromCache( @PathParam( "userId" ) String userId )
        throws RedbackServiceException;

    @Path( "guest" )
    @GET
    @Produces( { MediaType.APPLICATION_JSON } )
    @RedbackAuthorization( permissions = RedbackRoleConstants.USER_MANAGEMENT_USER_EDIT_OPERATION )
    User getGuestUser()
        throws RedbackServiceException;

    @Path( "guest" )
    @POST
    @Produces( { MediaType.APPLICATION_JSON } )
    @RedbackAuthorization( permissions = RedbackRoleConstants.USER_MANAGEMENT_USER_EDIT_OPERATION )
    User createGuestUser()
        throws RedbackServiceException;

    /**
     *
     *
     * @return*/
    @Path( "{userId}/register" )
    @POST
    @Produces( { MediaType.APPLICATION_JSON } )
    @RedbackAuthorization( noRestriction = true, noPermission = true )
    RegistrationKey registerUser( @PathParam( "userId" ) String userId,  UserRegistrationRequest userRegistrationRequest )
        throws RedbackServiceException;

    /**
     *
     * @param resetPasswordRequest contains username for send a password reset email
     */
    @Path( "{userId}/password/reset" )
    @POST
    @Produces( { MediaType.APPLICATION_JSON } )
    @Consumes( { MediaType.APPLICATION_JSON } )
    @RedbackAuthorization( noRestriction = true, noPermission = true )
    ActionStatus resetPassword( @PathParam( "userId" )String userId, ResetPasswordRequest resetPasswordRequest )
        throws RedbackServiceException;

    /**
     */
    @Path( "{userId}/permissions" )
    @GET
    @Produces( { MediaType.APPLICATION_JSON } )
    @RedbackAuthorization( permissions = RedbackRoleConstants.USER_MANAGEMENT_USER_LIST_OPERATION )
    Collection<Permission> getUserPermissions( @PathParam( "userId" ) String userName )
        throws RedbackServiceException;

    /**
     * @since 1.4
     */
    @Path( "{userId}/operations" )
    @GET
    @Produces( { MediaType.APPLICATION_JSON } )
    @RedbackAuthorization( permissions = RedbackRoleConstants.USER_MANAGEMENT_USER_LIST_OPERATION )
    Collection<Operation> getUserOperations( @PathParam( "userId" ) String userName )
        throws RedbackServiceException;

    /**
     * @return  the current logged user permissions, if no logged user guest permissions are returned
     * @since 1.4
     */
    @Path( "me/permissions" )
    @GET
    @Produces( { MediaType.APPLICATION_JSON } )
    @RedbackAuthorization( noRestriction = true, noPermission = true )
    Collection<Permission> getCurrentUserPermissions( )
        throws RedbackServiceException;

    /**
     * @return the current logged user operations, if no logged user guest operations are returned
     * @since 1.4
     */
    @Path( "me/operations" )
    @GET
    @Produces( { MediaType.APPLICATION_JSON } )
    @RedbackAuthorization( noRestriction = true, noPermission = true )
    Collection<Operation> getCurrentUserOperations( )
        throws RedbackServiceException;


    @Path( "{userId}/register/{key}/validate" )
    @GET
    @Produces( {MediaType.APPLICATION_JSON} )
    @RedbackAuthorization( noRestriction = true, noPermission = true )
    VerificationStatus validateUserRegistration( @PathParam( "userId" ) String userId, @PathParam( "key" ) String key )
        throws RedbackServiceException;
}