com.symphony.api.agent.DatafeedApi Maven / Gradle / Ivy
package com.symphony.api.agent;
import com.symphony.api.model.AckId;
import com.symphony.api.model.Datafeed;
import com.symphony.api.model.Error;
import com.symphony.api.model.MessageList;
import com.symphony.api.model.V2Error;
import com.symphony.api.model.V2MessageList;
import com.symphony.api.model.V4EventList;
import com.symphony.api.model.V5Datafeed;
import com.symphony.api.model.V5DatafeedCreateBody;
import com.symphony.api.model.V5EventList;
import java.io.InputStream;
import java.io.OutputStream;
import java.util.List;
import java.util.Map;
import javax.ws.rs.*;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.MediaType;
import org.apache.cxf.jaxrs.ext.multipart.*;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.media.ArraySchema;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
/**
* Agent API
*
* This document refers to Symphony API calls to send and receive messages and content. They need the on-premise Agent installed to perform decryption/encryption of content. - sessionToken and keyManagerToken can be obtained by calling the authenticationAPI on the symphony back end and the key manager respectively. Refer to the methods described in authenticatorAPI.yaml. - Actions are defined to be atomic, ie will succeed in their entirety or fail and have changed nothing. - If it returns a 40X status then it will have sent no message to any stream even if a request to aome subset of the requested streams would have succeeded. - If this contract cannot be met for any reason then this is an error and the response code will be 50X. - MessageML is a markup language for messages. See reference here: https://rest-api.symphony.com/docs/messagemlv2 - **Real Time Events**: The following events are returned when reading from a real time messages and events stream (\"datafeed\"). These events will be returned for datafeeds created with the v5 endpoints. To know more about the endpoints, refer to Create Messages/Events Stream and Read Messages/Events Stream. Unless otherwise specified, all events were added in 1.46.
*
*/
@Path("/")
public interface DatafeedApi {
/**
* Create a new real time messages / events stream (\"datafeed\").
*
* _Available on Agent 2.57.0 and above._ The datafeed provides messages and events from all conversations that the user is in. The types of events surfaced in the datafeed can be found in the Real Time Events list. (see definition on top of the file) Returns the ID of the datafeed that has just been created. This ID should then be used as input to the Read Messages/Events Stream v4 endpoint.
*
*/
@POST
@Path("/v5/datafeeds")
@Consumes({ "application/json" })
@Produces({ "application/json" })
@Operation(summary = "Create a new real time messages / events stream (\"datafeed\").", tags={ })
@ApiResponses(value = {
@ApiResponse(responseCode = "201", description = "Datafeed sucessfully created.", content = @Content(schema = @Schema(implementation = V5Datafeed.class))),
@ApiResponse(responseCode = "400", description = "Bad request.", content = @Content(schema = @Schema(implementation = V2Error.class))),
@ApiResponse(responseCode = "401", description = "Unauthorized.", content = @Content(schema = @Schema(implementation = V2Error.class))),
@ApiResponse(responseCode = "500", description = "Internal server error.", content = @Content(schema = @Schema(implementation = V2Error.class))) })
public V5Datafeed createDatafeed(@HeaderParam("sessionToken") String sessionToken, @HeaderParam("keyManagerToken") String keyManagerToken, V5DatafeedCreateBody body);
/**
* Delete the specified real time message / event stream (\"datafeed\").
*
* _Available on Agent 2.57.0 and above._ The datafeed provides messages and events from all conversations that the user is in. The types of events surfaced in the datafeed can be found in the Real Time Events list. (see definition on top of the file) Delete the specified datafeed.
*
*/
@DELETE
@Path("/v5/datafeeds/{datafeedId}")
@Produces({ "*/*" })
@Operation(summary = "Delete the specified real time message / event stream (\"datafeed\").", tags={ })
@ApiResponses(value = {
@ApiResponse(responseCode = "204", description = "Datafeed successfully deleted.", content = @Content(schema = @Schema(implementation = V2Error.class))),
@ApiResponse(responseCode = "400", description = "Bad request.", content = @Content(schema = @Schema(implementation = V2Error.class))),
@ApiResponse(responseCode = "401", description = "Unauthorized.", content = @Content(schema = @Schema(implementation = V2Error.class))),
@ApiResponse(responseCode = "500", description = "Internal server error.", content = @Content(schema = @Schema(implementation = V2Error.class))) })
public V2Error deleteDatafeed(@PathParam("datafeedId") String datafeedId, @HeaderParam("sessionToken") String sessionToken, @HeaderParam("keyManagerToken") String keyManagerToken);
/**
* Read list of real time messages / events stream (\"datafeed\").
*
* _Available on Agent 2.57.0 and above._ The datafeed provides messages and events from all conversations that the user is in. The types of events surfaced in the datafeed can be found in the [Real Time Events](./docs/real-time-events.md) list. Returns the list of the datafeeds for the user. Any datafeed ID of the list can then be used as input to the Read Messages/Events Stream v4 endpoint.
*
*/
@GET
@Path("/v5/datafeeds")
@Produces({ "application/json" })
@Operation(summary = "Read list of real time messages / events stream (\"datafeed\").", tags={ })
@ApiResponses(value = {
@ApiResponse(responseCode = "200", description = "Datafeed sucessfully created.", content = @Content(array = @ArraySchema(schema = @Schema(implementation = V5Datafeed.class)))),
@ApiResponse(responseCode = "400", description = "Bad request.", content = @Content(schema = @Schema(implementation = V2Error.class))),
@ApiResponse(responseCode = "401", description = "Unauthorized.", content = @Content(schema = @Schema(implementation = V2Error.class))),
@ApiResponse(responseCode = "500", description = "Internal server error.", content = @Content(schema = @Schema(implementation = V2Error.class))) })
public List listDatafeed(@HeaderParam("sessionToken") String sessionToken, @HeaderParam("keyManagerToken") String keyManagerToken, @QueryParam("tag")String tag);
/**
* Read the specified real time message / event stream (\"datafeed\").
*
* _Available on Agent 2.57.0 and above._ The datafeed provides messages and events from all conversations that the user is in. The types of events surfaced in the datafeed can be found in the Real Time Events list. (see definition on top of the file) Read the specified datafeed. The ackId sent as parameter can be empty for the first call. In the response an ackId will be sent back and it can be used for the next call: in this way you acknowledge that you have received the events that came with that ackId; datafeed will remove the events associated with that ackId from your queue
*
*/
@POST
@Path("/v5/datafeeds/{datafeedId}/read")
@Consumes({ "application/json" })
@Produces({ "application/json" })
@Operation(summary = "Read the specified real time message / event stream (\"datafeed\").", tags={ })
@ApiResponses(value = {
@ApiResponse(responseCode = "200", description = "Datafeed successfully read.", content = @Content(schema = @Schema(implementation = V5EventList.class))),
@ApiResponse(responseCode = "400", description = "Bad request.", content = @Content(schema = @Schema(implementation = V2Error.class))),
@ApiResponse(responseCode = "401", description = "Unauthorized.", content = @Content(schema = @Schema(implementation = V2Error.class))),
@ApiResponse(responseCode = "403", description = "Forbidden.", content = @Content(schema = @Schema(implementation = V2Error.class))),
@ApiResponse(responseCode = "500", description = "Internal server error.", content = @Content(schema = @Schema(implementation = V2Error.class))) })
public V5EventList readDatafeed(@HeaderParam("sessionToken") String sessionToken, @HeaderParam("keyManagerToken") String keyManagerToken, @PathParam("datafeedId") String datafeedId, AckId body);
/**
* Create a new real time message event stream.
*
* A datafeed provides the messages in all conversations that a user is in. System messages like new users joining a chatroom are not part of the datafeed. A datafeed will expire after if it isn't read before its capacity is reached.
*
*/
@POST
@Path("/v1/datafeed/create")
@Produces({ "application/json" })
@Operation(summary = "Create a new real time message event stream.", tags={ })
@ApiResponses(value = {
@ApiResponse(responseCode = "200", description = "OK", content = @Content(schema = @Schema(implementation = Datafeed.class))),
@ApiResponse(responseCode = "400", description = "Client error.", content = @Content(schema = @Schema(implementation = Error.class))),
@ApiResponse(responseCode = "401", description = "Unauthorized: Session tokens invalid.", content = @Content(schema = @Schema(implementation = Error.class))),
@ApiResponse(responseCode = "403", description = "Forbidden: Caller lacks necessary entitlement.", content = @Content(schema = @Schema(implementation = Error.class))),
@ApiResponse(responseCode = "500", description = "Server error, see response body for further details.", content = @Content(schema = @Schema(implementation = Error.class))),
@ApiResponse(responseCode = "503", description = "Max number of data feeds reached.", content = @Content(schema = @Schema(implementation = Error.class))) })
public Datafeed v1DatafeedCreatePost(@HeaderParam("sessionToken") String sessionToken, @HeaderParam("keyManagerToken") String keyManagerToken);
/**
* Read a given datafeed.
*
* Read messages from the given datafeed. If no more messages are available then this method will block. It is intended that the client should re-call this method as soon as it has processed the messages received in the previous call. If the client is able to consume messages more quickly than they become available then each call will initially block, there is no need to delay before re-calling this method. A datafeed will expire if its unread capacity is reached. A datafeed can only be consumed by one client thread at a time. E.g. polling the datafeed by two threads may lead to messages being delivered out of order.
*
*/
@GET
@Path("/v1/datafeed/{id}/read")
@Produces({ "application/json" })
@Operation(summary = "Read a given datafeed.", tags={ })
@ApiResponses(value = {
@ApiResponse(responseCode = "200", description = "List of messages that have occurred since last time this URL was polled. If the list is empty, it means the request has reached its timeout, and the client should poll again.", content = @Content(schema = @Schema(implementation = MessageList.class))),
@ApiResponse(responseCode = "204", description = "No Messages."),
@ApiResponse(responseCode = "400", description = "Client error, see response body for further details.", content = @Content(schema = @Schema(implementation = Error.class))),
@ApiResponse(responseCode = "401", description = "Unauthorized: Session tokens invalid.", content = @Content(schema = @Schema(implementation = Error.class))),
@ApiResponse(responseCode = "403", description = "Forbidden: Caller lacks necessary entitlement.", content = @Content(schema = @Schema(implementation = Error.class))),
@ApiResponse(responseCode = "500", description = "Server error, see response body for further details.", content = @Content(schema = @Schema(implementation = Error.class))) })
public MessageList v1DatafeedIdReadGet(@PathParam("id") String id, @HeaderParam("sessionToken") String sessionToken, @HeaderParam("keyManagerToken") String keyManagerToken, @QueryParam("maxMessages")Integer maxMessages);
/**
* Read a given datafeed.
*
* Read messages from the given datafeed. If no more messages are available then this method will block. It is intended that the client should re-call this method as soon as it has processed the messages received in the previous call. If the client is able to consume messages more quickly than they become available then each call will initially block, there is no need to delay before re-calling this method. A datafeed will expire if its unread capacity is reached. A datafeed can only be consumed by one client thread at a time. E.g. polling the datafeed by two threads may lead to messages being delivered out of order.
*
*/
@GET
@Path("/v2/datafeed/{id}/read")
@Produces({ "application/json" })
@Operation(summary = "Read a given datafeed.", tags={ })
@ApiResponses(value = {
@ApiResponse(responseCode = "200", description = "List of messages that have occurred since last time this URL was polled. If the list is empty, it means the request has reached its timeout, and the client should poll again.", content = @Content(schema = @Schema(implementation = V2MessageList.class))),
@ApiResponse(responseCode = "204", description = "No Messages."),
@ApiResponse(responseCode = "400", description = "Client error, see response body for further details.", content = @Content(schema = @Schema(implementation = Error.class))),
@ApiResponse(responseCode = "401", description = "Unauthorized: Session tokens invalid.", content = @Content(schema = @Schema(implementation = Error.class))),
@ApiResponse(responseCode = "403", description = "Forbidden: Caller lacks necessary entitlement.", content = @Content(schema = @Schema(implementation = Error.class))),
@ApiResponse(responseCode = "500", description = "Server error, see response body for further details.", content = @Content(schema = @Schema(implementation = Error.class))) })
public V2MessageList v2DatafeedIdReadGet(@PathParam("id") String id, @HeaderParam("sessionToken") String sessionToken, @HeaderParam("keyManagerToken") String keyManagerToken, @QueryParam("maxMessages")Integer maxMessages);
/**
* Create a new real time message event stream.
*
* A datafeed provides the messages in all conversations that a user is in. This also includes system messages like new users joining a chatroom. A datafeed will expire if it isn't read before its capacity is reached.
*
*/
@POST
@Path("/v4/datafeed/create")
@Produces({ "application/json" })
@Operation(summary = "Create a new real time message event stream.", tags={ })
@ApiResponses(value = {
@ApiResponse(responseCode = "200", description = "OK", content = @Content(schema = @Schema(implementation = Datafeed.class))),
@ApiResponse(responseCode = "400", description = "Client error.", content = @Content(schema = @Schema(implementation = V2Error.class))),
@ApiResponse(responseCode = "401", description = "Unauthorized: Session tokens invalid.", content = @Content(schema = @Schema(implementation = V2Error.class))),
@ApiResponse(responseCode = "403", description = "Forbidden: Caller lacks necessary entitlement.", content = @Content(schema = @Schema(implementation = V2Error.class))),
@ApiResponse(responseCode = "500", description = "Server error, see response body for further details.", content = @Content(schema = @Schema(implementation = V2Error.class))),
@ApiResponse(responseCode = "503", description = "Max number of data feeds reached.", content = @Content(schema = @Schema(implementation = V2Error.class))) })
public Datafeed v4DatafeedCreatePost(@HeaderParam("sessionToken") String sessionToken, @HeaderParam("keyManagerToken") String keyManagerToken);
/**
* Read a given datafeed.
*
* Read messages from the given datafeed. If no more messages are available then this method will block. It is intended that the client should re-call this method as soon as it has processed the messages received in the previous call. If the client is able to consume messages more quickly than they become available then each call will initially block, there is no need to delay before re-calling this method. A datafeed will expire if its unread capacity is reached. A datafeed can only be consumed by one client thread at a time. E.g. polling the datafeed by two threads may lead to messages being delivered out of order.
*
*/
@GET
@Path("/v4/datafeed/{id}/read")
@Produces({ "application/json" })
@Operation(summary = "Read a given datafeed.", tags={ })
@ApiResponses(value = {
@ApiResponse(responseCode = "200", description = "List of messages that have occurred since last time this URL was polled. If the list is empty, it means the request has reached its timeout, and the client should poll again.", content = @Content(schema = @Schema(implementation = V4EventList.class))),
@ApiResponse(responseCode = "204", description = "No Messages."),
@ApiResponse(responseCode = "400", description = "Client error, see response body for further details.", content = @Content(schema = @Schema(implementation = V2Error.class))),
@ApiResponse(responseCode = "401", description = "Unauthorized: Session tokens invalid.", content = @Content(schema = @Schema(implementation = V2Error.class))),
@ApiResponse(responseCode = "403", description = "Forbidden: Caller lacks necessary entitlement.", content = @Content(schema = @Schema(implementation = V2Error.class))),
@ApiResponse(responseCode = "500", description = "Server error, see response body for further details.", content = @Content(schema = @Schema(implementation = V2Error.class))) })
public V4EventList v4DatafeedIdReadGet(@PathParam("id") String id, @HeaderParam("sessionToken") String sessionToken, @HeaderParam("keyManagerToken") String keyManagerToken, @QueryParam("limit")Integer limit);
}