diff --git a/.DS_Store b/.DS_Store index 6d689c1..bb5a37b 100644 Binary files a/.DS_Store and b/.DS_Store differ diff --git a/src/main/java/org/gcube/portal/social/networking/ws/inputs/Recipient.java b/src/main/java/org/gcube/portal/social/networking/ws/inputs/Recipient.java index 282156c..c3383fa 100644 --- a/src/main/java/org/gcube/portal/social/networking/ws/inputs/Recipient.java +++ b/src/main/java/org/gcube/portal/social/networking/ws/inputs/Recipient.java @@ -26,7 +26,7 @@ public class Recipient implements Serializable{ /* * @param "The recipient of the message", */ - @DocumentationExample("andrea.rossi") + @DocumentationExample("john.smith") private String id; public Recipient() { diff --git a/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/Comments.java b/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/Comments.java index 32db797..a2f0c7e 100644 --- a/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/Comments.java +++ b/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/Comments.java @@ -23,6 +23,8 @@ import org.gcube.portal.social.networking.ws.utils.ErrorMessages; import org.gcube.portal.social.networking.ws.utils.Filters; import org.slf4j.LoggerFactory; +import com.webcohesion.enunciate.metadata.rs.RequestHeader; +import com.webcohesion.enunciate.metadata.rs.RequestHeaders; import com.webcohesion.enunciate.metadata.rs.ResponseCode; import com.webcohesion.enunciate.metadata.rs.StatusCodes; @@ -30,11 +32,10 @@ import com.webcohesion.enunciate.metadata.rs.StatusCodes; * REST interface for the social networking library (comments). */ @Path("2/comments") -/** - * Resource endpoint for Comment (version 2) - * @author Costantino Perciante at ISTI-CNR - * (costantino.perciante@isti.cnr.it) - */ +@RequestHeaders ({ + @RequestHeader( name = "Authorization", description = "Bearer token, see https://dev.d4science.org/how-to-access-resources"), + @RequestHeader( name = "Content-Type", description = "application/json") + }) public class Comments { // Logger diff --git a/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/FullTextSearch.java b/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/FullTextSearch.java index 5d9abc6..d92835f 100644 --- a/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/FullTextSearch.java +++ b/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/FullTextSearch.java @@ -40,6 +40,8 @@ import org.gcube.vomanagement.usermanagement.model.GCubeGroup; import org.gcube.vomanagement.usermanagement.model.GCubeUser; import org.slf4j.LoggerFactory; +import com.webcohesion.enunciate.metadata.rs.RequestHeader; +import com.webcohesion.enunciate.metadata.rs.RequestHeaders; import com.webcohesion.enunciate.metadata.rs.ResponseCode; import com.webcohesion.enunciate.metadata.rs.StatusCodes; @@ -47,6 +49,10 @@ import com.webcohesion.enunciate.metadata.rs.StatusCodes; * REST interface for the social networking library (post and its comments). */ @Path("2/full-text-search") +@RequestHeaders ({ + @RequestHeader( name = "Authorization", description = "Bearer token, see https://dev.d4science.org/how-to-access-resources"), + @RequestHeader( name = "Content-Type", description = "application/json") + }) public class FullTextSearch { // Logger diff --git a/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/HashTags.java b/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/HashTags.java index a341cfa..2b85b5f 100644 --- a/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/HashTags.java +++ b/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/HashTags.java @@ -19,14 +19,19 @@ import org.gcube.portal.social.networking.ws.utils.CassandraConnection; import org.gcube.portal.social.networking.ws.utils.ErrorMessages; import org.slf4j.LoggerFactory; +import com.webcohesion.enunciate.metadata.rs.RequestHeader; +import com.webcohesion.enunciate.metadata.rs.RequestHeaders; import com.webcohesion.enunciate.metadata.rs.ResponseCode; import com.webcohesion.enunciate.metadata.rs.StatusCodes; /** * REST interface for the social networking library (hash tags). - * @author Costantino Perciante at ISTI-CNR */ @Path("2/hashtags") +@RequestHeaders ({ + @RequestHeader( name = "Authorization", description = "Bearer token, see https://dev.d4science.org/how-to-access-resources"), + @RequestHeader( name = "Content-Type", description = "application/json") + }) public class HashTags { // Logger diff --git a/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/Messages.java b/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/Messages.java index 2f2388b..e462226 100644 --- a/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/Messages.java +++ b/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/Messages.java @@ -44,6 +44,8 @@ import org.gcube.vomanagement.usermanagement.exception.UserRetrievalFault; import org.gcube.vomanagement.usermanagement.model.GCubeUser; import org.slf4j.LoggerFactory; +import com.webcohesion.enunciate.metadata.rs.RequestHeader; +import com.webcohesion.enunciate.metadata.rs.RequestHeaders; import com.webcohesion.enunciate.metadata.rs.ResponseCode; import com.webcohesion.enunciate.metadata.rs.StatusCodes; @@ -53,11 +55,25 @@ import com.webcohesion.enunciate.metadata.rs.StatusCodes; * (costantino.perciante@isti.cnr.it) */ @Path("2/messages") +@RequestHeaders ({ + @RequestHeader( name = "Authorization", description = "Bearer token, see https://dev.d4science.org/how-to-access-resources"), + @RequestHeader( name = "Content-Type", description = "application/json") + }) public class Messages { // Logger private static final org.slf4j.Logger logger = LoggerFactory.getLogger(Messages.class); + /** + * Write a message to another user. The sender is the token's owner by default + * @responseExample application/json {"success": true, "message": null, "result": "556142e3-d6f5-4550-b2fa-abe5626625d3"} + * @param input The message to write" + * @param httpServletRequest + * @return see response example + * @throws ValidationException + * @throws UserManagementSystemException + * @throws UserRetrievalFault + */ @POST @Path("write-message/") @Consumes(MediaType.APPLICATION_JSON) @@ -66,15 +82,6 @@ public class Messages { @ResponseCode ( code = 200, condition = "Successful write a message. Its id is reported in the 'result' field of the returned object"), @ResponseCode ( code = 500, condition = ErrorMessages.ERROR_IN_API_RESULT) }) - /** - * Write a message to another user. The sender is the token's owner by default - * @param input The message to write" - * @param httpServletRequest - * @return - * @throws ValidationException - * @throws UserManagementSystemException - * @throws UserRetrievalFault - */ public Response writeMessage( @NotNull(message="Message to send is missing") @Valid diff --git a/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/Notifications.java b/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/Notifications.java index d277e2a..a2d7e26 100644 --- a/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/Notifications.java +++ b/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/Notifications.java @@ -38,14 +38,19 @@ import org.gcube.portal.social.networking.ws.utils.ErrorMessages; import org.gcube.vomanagement.usermanagement.model.GCubeUser; import org.slf4j.LoggerFactory; +import com.webcohesion.enunciate.metadata.rs.RequestHeader; +import com.webcohesion.enunciate.metadata.rs.RequestHeaders; import com.webcohesion.enunciate.metadata.rs.ResponseCode; import com.webcohesion.enunciate.metadata.rs.StatusCodes; /** * REST interface for the social networking library (notifications). - * @author Costantino Perciante at ISTI-CNR */ @Path("2/notifications") +@RequestHeaders ({ + @RequestHeader( name = "Authorization", description = "Bearer token, see https://dev.d4science.org/how-to-access-resources"), + @RequestHeader( name = "Content-Type", description = "application/json") + }) public class Notifications { // Logger diff --git a/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/People.java b/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/People.java index 24b3a13..be9024a 100644 --- a/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/People.java +++ b/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/People.java @@ -26,14 +26,19 @@ import org.gcube.vomanagement.usermanagement.model.GCubeRole; import org.gcube.vomanagement.usermanagement.model.GCubeUser; import org.slf4j.LoggerFactory; +import com.webcohesion.enunciate.metadata.rs.RequestHeader; +import com.webcohesion.enunciate.metadata.rs.RequestHeaders; import com.webcohesion.enunciate.metadata.rs.ResponseCode; import com.webcohesion.enunciate.metadata.rs.StatusCodes; /** - * REST interface for the social networking library (people). Used by OAUTH 2.0 apps/users. - * @author Costantino Perciante at ISTI-CNR + * REST interface for the social service (people). Used by OAUTH 2.0 apps/users. */ +@RequestHeaders ({ + @RequestHeader( name = "Authorization", description = "Bearer token, see https://dev.d4science.org/how-to-access-resources"), + @RequestHeader( name = "Content-Type", description = "application/json") + }) @Path("2/people") public class People { @@ -46,7 +51,7 @@ public class People { @ResponseCode ( code = 500, condition = ErrorMessages.ERROR_IN_API_RESULT) }) /** - * + * @responseExample application/json { "success" : true, "message" : null, "result" : { "roles" : [ ], "context" : "***", "avatar" : "https://*****3D", "fullname" : "John Smith", "username" : "john.smith" } } * @return the user's profile. The user in this case is the one bound to the token */ public Response getProfile(){ diff --git a/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/Posts.java b/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/Posts.java index cba4649..6c09d79 100644 --- a/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/Posts.java +++ b/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/Posts.java @@ -33,14 +33,19 @@ import org.gcube.portal.social.networking.ws.utils.Filters; import org.gcube.portal.social.networking.ws.utils.SocialUtils; import org.slf4j.LoggerFactory; +import com.webcohesion.enunciate.metadata.rs.RequestHeader; +import com.webcohesion.enunciate.metadata.rs.RequestHeaders; import com.webcohesion.enunciate.metadata.rs.ResponseCode; import com.webcohesion.enunciate.metadata.rs.StatusCodes; /** - * REST interface for the social networking library (feeds). - * @author Costantino Perciante at ISTI-CNR + * REST interface for the social networking library (posts). */ @Path("2/posts") +@RequestHeaders ({ + @RequestHeader( name = "Authorization", description = "Bearer token, see https://dev.d4science.org/how-to-access-resources"), + @RequestHeader( name = "Content-Type", description = "application/json") + }) public class Posts { // Logger diff --git a/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/Tokens.java b/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/Tokens.java index d89288a..1c934b7 100644 --- a/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/Tokens.java +++ b/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/Tokens.java @@ -27,9 +27,9 @@ import com.webcohesion.enunciate.metadata.rs.StatusCodes; /** * REST interface for the social networking library (tokens). - * @author Costantino Perciante at ISTI-CNR */ @Path("2/tokens") +@Deprecated public class Tokens { // Logger diff --git a/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/Users.java b/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/Users.java index 38ac6fd..3a8f28a 100644 --- a/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/Users.java +++ b/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/Users.java @@ -37,14 +37,19 @@ import org.gcube.vomanagement.usermanagement.model.GCubeRole; import org.gcube.vomanagement.usermanagement.model.GCubeUser; import org.slf4j.LoggerFactory; +import com.webcohesion.enunciate.metadata.rs.RequestHeader; +import com.webcohesion.enunciate.metadata.rs.RequestHeaders; import com.webcohesion.enunciate.metadata.rs.ResponseCode; import com.webcohesion.enunciate.metadata.rs.StatusCodes; /** * REST interface for the social networking library (users). - * @author Costantino Perciante at ISTI-CNR */ @Path("2/users") +@RequestHeaders ({ + @RequestHeader( name = "Authorization", description = "Bearer token, see https://dev.d4science.org/how-to-access-resources"), + @RequestHeader( name = "Content-Type", description = "application/json") + }) public class Users { // Logger @@ -186,6 +191,11 @@ public class Users { return Response.status(status).entity(responseBean).build(); } + /** + * Get the profile associated to the token + * @responseExample application/json { "success" : true, "message" : null, "result" : { "user_id" : 23769487, "username" : "john.smith", "email" : "********", "first_name" : "John", "middle_name" : "", "last_name" : "Smith", "fullname" : "John Smith", "registration_date" : 1475151491415, "user_avatar_url" : "https://******D", "male" : true, "job_title" : "", "location_industry" : "no", "custom_attrs_map" : null, "email_addresses" : [ ], "screen_name" : "john.smith", "user_avatar_id" : "https://****sY%3D" } } + * @return the user's profile. The user is the one owning the token + */ @GET @Path("get-profile") @Produces(MediaType.APPLICATION_JSON) @@ -193,10 +203,6 @@ public class Users { @ResponseCode ( code = 200, condition = "The user's profile is reported in the 'result' field of the returned object"), @ResponseCode ( code = 500, condition = ErrorMessages.ERROR_IN_API_RESULT) }) - /** - * - * @return the user's profile. The user is the one owning the token - */ public Response getUserProfile(){ Caller caller = AuthorizationProvider.instance.get(); @@ -246,6 +252,23 @@ public class Users { } }; + /** + * @responseExample application/json { + "id": "john.smith", + "roles": [], + "picture": "https://***gAJ4uVWTA74xwQ6%2FCA72RRinysY%3D", + "name": "John Smith", + "middle_name": "", + "male": true, + "location_industry": "no", + "given_name": "John", + "email": "******", + "job_title": "", + "family_name": "Smith", + "verified_email": true +} + * @return the user's profile compliant with oauth + */ @GET @Path("get-oauth-profile") @Produces(MediaType.APPLICATION_JSON) @@ -287,7 +310,18 @@ public class Users { return Response.status(status).entity(userWithEmailVerified).build(); } - + /** + * @responseExample application/json { + "success": true, + "message": null, + "result": [ + "john.smith", + "marco.polo" + ] +} + * Get the list of usernames belonging to a given context + * @return the list of usernames for the user belonging to the context linked to the provided auth token + */ @GET @Path("get-all-usernames") @Produces(MediaType.APPLICATION_JSON) @@ -295,10 +329,6 @@ public class Users { @ResponseCode ( code = 200, condition = "The list of usernames is put into the 'result' field of the returned object"), @ResponseCode ( code = 500, condition = ErrorMessages.ERROR_IN_API_RESULT) }) - /** - * Get the list of usernames belonging to a given context - * @return the list of usernames for the user belonging to the context linked to the provided auth token - */ public Response getAllUserNames(){ ResponseBean responseBean = new ResponseBean(); @@ -338,7 +368,11 @@ public class Users { return Response.status(status).entity(responseBean).build(); } - + + /** + * Get the map of couples username/fullname of the users belonging to a given context + * @return the map of couples username/fullname of the users belonging to the context linked to the provided token. + */ @GET @Path("get-all-fullnames-and-usernames") @StatusCodes ({ @@ -346,10 +380,6 @@ public class Users { @ResponseCode ( code = 500, condition = ErrorMessages.ERROR_IN_API_RESULT) }) @Produces(MediaType.APPLICATION_JSON) - /** - * Get the map of couples username/fullname of the users belonging to a given context - * @return the map of couples username/fullname of the users belonging to the context linked to the provided token. - */ public Response getFullnamesAndUsernames(){ ResponseBean responseBean = new ResponseBean(); @@ -390,6 +420,11 @@ public class Users { return Response.status(status).entity(responseBean).build(); } + /** + * Get the list of users having a given global-role, e.g. 'Administrator'. (Legacy) + * @param roleName the name of the role to be checked (e.g. Administrator) + * @return the list of users having a given global-role + */ @GET @Path("get-usernames-by-global-role") @Produces(MediaType.APPLICATION_JSON) @@ -397,11 +432,6 @@ public class Users { @ResponseCode ( code = 200, condition = "The list is put into the 'result' field of the returned object"), @ResponseCode ( code = 500, condition = ErrorMessages.ERROR_IN_API_RESULT) }) - /** - * Get the list of users having a given global-role, e.g. 'Administrator'. (Legacy) - * @param roleName the name of the role to be checked (e.g. Administrator) - * @return the list of users having a given global-role - */ public Response getUsernamesByGlobalRole( @QueryParam("role-name") String roleName){ @@ -443,12 +473,24 @@ public class Users { return Response.status(status).entity(responseBean).build(); } + /** + * @pathExample /get-usernames-by-role?role-name=VRE-Manager + * @param roleName the role name + * @return the usernames having the role in the VRE + * @responseExample application/json { + "success": true, + "message": null, + "result": [ + "john.smith", + "marco.polo" + ] +} + */ @GET @Path("get-usernames-by-role") @Produces(MediaType.APPLICATION_JSON) public Response getUsernamesByRole( @QueryParam("role-name") String roleName){ - ResponseBean responseBean = new ResponseBean(); Status status = Status.OK; String context = ScopeProvider.instance.get(); @@ -500,6 +542,7 @@ public class Users { @GET @Path("user-exists") @Produces(MediaType.APPLICATION_JSON) + @Deprecated public Response existUser(@QueryParam("username") String username){ ResponseBean responseBean = new ResponseBean(); diff --git a/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/VREs.java b/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/VREs.java index 31486d4..3a374c6 100644 --- a/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/VREs.java +++ b/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/VREs.java @@ -29,17 +29,42 @@ import org.json.simple.JSONArray; import org.json.simple.JSONObject; import org.slf4j.LoggerFactory; +import com.webcohesion.enunciate.metadata.rs.RequestHeader; +import com.webcohesion.enunciate.metadata.rs.RequestHeaders; + /** * REST interface for the social networking library (vres). - * @author Costantino Perciante at ISTI-CNR */ @Path("2/vres") +@RequestHeaders ({ + @RequestHeader( name = "Authorization", description = "Bearer token, see https://dev.d4science.org/how-to-access-resources"), + @RequestHeader( name = "Content-Type", description = "application/json") + }) public class VREs { // Logger private static final org.slf4j.Logger logger = LoggerFactory.getLogger(Users.class); + /** + * @responseExample application/json { + "success" : true, + "message" : null, + "result" : [ { + "name" : "NextNext", + "context" : "/gcube/devNext/NextNext", + "description" : "NextNext description AAA" + }, { + "name" : "devVRE", + "context" : "/gcube/devsec/devVRE", + "description" : "devVRE description BBB" + } ] +} + * @pathExample /get-my-vres?getManagers=false + * @param getManagers set true if you also want to know the VRE-Managers + * @return the list of vres along with some metadata + * @throws ValidationException + */ @SuppressWarnings("unchecked") @GET @Path("get-my-vres/")