| 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.SelfUserData; |
| import org.apache.archiva.redback.rest.api.model.v2.PagedResult; |
| 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, |
| resource = "{userId}" ) |
| 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 = "422", 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 = "422", 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" ), |
| @ApiResponse( responseCode = "403", description = "The authenticated user has not the permission for deletion." ) |
| } |
| ) |
| 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 = "Updates an existing 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." ), |
| @ApiResponse( responseCode = "403", description = "The authenticated user has not the permission for update." ) |
| } |
| ) |
| User updateUser( @PathParam( "userId" ) String userId, User user ) |
| throws RedbackServiceException; |
| |
| /** |
| */ |
| @Path( "{userId}/lock/set" ) |
| @POST |
| @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 locking was successful" |
| ), |
| @ApiResponse( responseCode = "404", description = "User does not exist" ), |
| @ApiResponse( responseCode = "403", description = "The authenticated user has not the permission for locking." ) |
| } |
| ) |
| void lockUser( @PathParam( "userId" ) String userId ) |
| throws RedbackServiceException; |
| |
| /** |
| */ |
| @Path( "{userId}/lock/clear" ) |
| @POST |
| @Produces( { MediaType.APPLICATION_JSON } ) |
| @RedbackAuthorization( permissions = RedbackRoleConstants.USER_MANAGEMENT_USER_EDIT_OPERATION ) |
| @io.swagger.v3.oas.annotations.Operation( summary = "Unlocks a user", |
| responses = { |
| @ApiResponse( responseCode = "200", |
| description = "If unlocking was successful" |
| ), |
| @ApiResponse( responseCode = "404", description = "User does not exist" ), |
| @ApiResponse( responseCode = "403", description = "The authenticated user has not the permission for unlock." ) |
| } |
| ) |
| void unlockUser( @PathParam( "userId" ) String userId ) |
| throws RedbackServiceException; |
| |
| |
| /** |
| */ |
| @Path( "{userId}/password/require/set" ) |
| @POST |
| @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 password change require flag was set" |
| ), |
| @ApiResponse( responseCode = "404", description = "User does not exist" ), |
| @ApiResponse( responseCode = "403", description = "The authenticated user has not the permission for editing." ) |
| |
| } |
| ) |
| void setRequirePasswordChangeFlag( @PathParam( "userId" ) String userId ) |
| throws RedbackServiceException; |
| |
| /** |
| */ |
| @Path( "{userId}/password/require/clear" ) |
| @POST |
| @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 password change require flag was unset" |
| ), |
| @ApiResponse( responseCode = "404", description = "User does not exist" ), |
| @ApiResponse( responseCode = "403", description = "The authenticated user has not the permission for editing." ) |
| |
| } |
| ) |
| void clearRequirePasswordChangeFlag( @PathParam( "userId" ) String userId ) |
| throws RedbackServiceException; |
| |
| |
| /** |
| * Update only the current logged in user and this fields: fullname, email, password. |
| * The service verifies the current logged user with the one passed in the method |
| * @return |
| */ |
| @Path( "me" ) |
| @PUT |
| @Produces( { MediaType.APPLICATION_JSON } ) |
| @RedbackAuthorization( noPermission = true ) |
| @io.swagger.v3.oas.annotations.Operation( summary = "Updates information of the current logged in user", |
| responses = { |
| @ApiResponse( responseCode = "200", |
| description = "If user data has been updated" |
| ), |
| @ApiResponse( responseCode = "401", description = "User is not logged in" ), |
| @ApiResponse( responseCode = "400", description = "Provided data is not valid" ) |
| } |
| ) |
| User updateMe( SelfUserData user ) |
| throws RedbackServiceException; |
| |
| @Path( "me" ) |
| @GET |
| @Produces( { MediaType.APPLICATION_JSON } ) |
| @RedbackAuthorization( noPermission = true ) |
| @io.swagger.v3.oas.annotations.Operation( summary = "Gets information of the current logged in user", |
| responses = { |
| @ApiResponse( responseCode = "200", |
| description = "If user data is returned" |
| ), |
| @ApiResponse( responseCode = "401", description = "User is not logged in" ), |
| } |
| ) |
| User getLoggedInUser( ) 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, |
| resource = "{userId}") |
| @io.swagger.v3.oas.annotations.Operation( summary = "Clears the cache for the user", |
| responses = { |
| @ApiResponse( responseCode = "200", |
| description = "If the cache was cleared properly" |
| ), |
| @ApiResponse( responseCode = "404", description = "User does not exist" ), |
| @ApiResponse( responseCode = "403", description = "The authenticated user has not the required permission." ) |
| } |
| ) |
| ActionStatus removeFromCache( @PathParam( "userId" ) String userId ) |
| throws RedbackServiceException; |
| |
| /** |
| * @return |
| */ |
| @Path( "{userId}/register" ) |
| @POST |
| @Produces( {MediaType.APPLICATION_JSON} ) |
| @RedbackAuthorization( noRestriction = true, noPermission = true ) |
| @io.swagger.v3.oas.annotations.Operation( summary = "Registers a new user", |
| responses = { |
| @ApiResponse( responseCode = "200", |
| description = "If the registration was successful, a registration key is returned" |
| ), |
| @ApiResponse( responseCode = "400", description = "If the registration request has invalid data" ), |
| } |
| ) |
| 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; |
| } |