These examples demonstrate how to send a JSON response using streaming and using default object serialization. When sending a response, you can send a response as a stream or serialize an object. There are advantages and disadvantages to either approach.
Pick a technique based on the needs of your integration. Using a streaming responses provides advantages in response time, instance performance, and content flexibility, but adds additional complexity to the script.
When using streaming, you are responsible for formatting the response, setting the response status, and setting the Content-Type header. When streaming a response, the requesting user receives a response quickly because the entire response does not need to be created before starting streaming. Using object serialization allows you to take advantage of ServiceNow provided serialization and content negotiation.
When serializing an object instead of streaming, the entire object must be created and serialized before the client receives a response.
Return a file stream from a REST controller in Spring Boot
This may delay the response, or require a large amount of system resources if the response object is very large. Responses using a different format must use streaming. This example returns the same Incident data as the streaming example, but collects all of the response data in an array before sending the response. Streaming vs object serialization When sending a response, you can send a response as a stream or serialize an object.
Streaming the response Using a streaming responses provides advantages in response time, instance performance, and content flexibility, but adds additional complexity to the script.The standard way of understanding the HTTP protocol is via the request reply pattern. However it's also possible for both parts of an HTTP 1. The advantages is that the sender can send data that is beyond the sender's memory limit, and the receiver can act on the data stream in chunks immediately instead of waiting for the entire data to arrive.
Basically you're either saving space or you're saving time. The advantages of streaming is elaborated in Wikipedia's Online algorithm article. Streaming is also the basis for HTML5 server sent events. So we're going to look at HTTP streaming architecture, and how to achieve streaming in a few different languages. In a larger context, each HTTP transaction itself represents an event as part of a larger event stream.
This reveals to us that the concepts of "streaming" is a context-specific concept, it's relative to what we consider the "stream" to be. Firstly we have to consider the HTTP headers that supports streaming. The Content-Length and Transfer-Encoding header should not be used together. The receiver will have no idea what the length of the body is and cannot estimate the download completion time.
If you do add a Content-Length header, make sure it matches the entire body in bytes, if it is incorrect, the behaviour of receivers is undefined. The Content-Length header will not allow streaming, but it is useful for large binary files, where you want to support partial content serving. This basically means resumable downloads, paused downloads, partial downloads, and multi-homed downloads.
This requires the use of an additional header called Range. This technique is called Byte serving. The use of Transfer-Encoding: chunked is what allows streaming within a single request or response. This means that the data is transmitted in a chunked manner, and does not impact the representation of the content. Officially an HTTP client is meant to send a request with a TE header field that specifies what kinds of transfer encodings the client is willing to accept.
This is not always sent, however most servers assume that clients can process chunked encodings. Each chunk starts with its byte length expressed as a hexadecimal number followed by optional parameters chunk extension and a terminating CRLF sequence, followed by the chunk data. The final chunk is terminated by a CRLF sequence. Chunk extensions can be used to indicate a message digest or an estimated progress.
They are just custom metadata that your layer 7 receiver needs to parse.Unlike basic HttpResponse objects, TemplateResponse objects retain the details of the context that was provided by the view to compute the response. The final output of the response is not computed until it is needed, later in the response process.
REST framework supports HTTP content negotiation by providing a Response class which allows you to return content that can be rendered into multiple content types, depending on the client request. Response objects are initialised with data, which should consist of native Python primitives. There's no requirement for you to use the Response class, you can also return regular HttpResponse or StreamingHttpResponse objects from your views if required. Using the Response class simply provides a nicer interface for returning content-negotiated Web API responses, that can be rendered to multiple formats.
Doing so ensures that the view can perform content negotiation and select the appropriate renderer for the response, before it is returned from the view. Unlike regular HttpResponse objects, you do not instantiate Response objects with rendered content. Instead you pass in unrendered data, which may consist of any Python primitives.
The renderers used by the Response class cannot natively handle complex datatypes such as Django model instances, so you need to serialize the data into primitive datatypes before creating the Response object.
You can use REST framework's Serializer classes to perform this data serialization, or use your own custom serialization. The rendered content of the response. Only required if HTMLRenderer or some other custom template renderer is the accepted renderer for the response. A dictionary of additional context information that will be passed to the renderer's. The Response class extends SimpleTemplateResponseand all the usual attributes and methods are also available on the response. For example you can set headers on the response in the standard way:.
As with any other TemplateResponsethis method is called to render the serialized data of the response into the final response content. You won't typically need to call. Responses Creating responses Response Attributes.
Arguments: data : The serialized data for the response. Defaults to See also status codes. Typically, this will be set automatically by the renderer as determined by content negotiation, but there may be some cases where you need to specify the content type explicitly.
Standard HttpResponse attributes The Response class extends SimpleTemplateResponseand all the usual attributes and methods are also available on the response.Have a look below at the official clients, framework integrations, and community-contributed libraries. Always feel free to get in touch at support getstream. Framework integrations are also available for Rails, Django, and Laravel. You're currently not logged in. Log in so we can add your API key and other information in the documentation snippets elsewhere on this page.
With the official JS client, you can see the tests and examine how the API requests are structured in your browser's network tab. You can review all of our open-source libraries at the official Stream GitHub page. Be sure to review the basics. Get stuck? No worries at all, feel free to contact support at any time. Note: Every request should also include the appropriate authorization header.
This allows you to send complex data structures to the Stream API endpoint! You can find more information on JWT at jwt. Libraries to generate JWT are available for most programming languages. The full list is available here. The authentication token must include the correct claims also called payload. Your application should generate the appropriate token; when using client-side auth, each user should have its own unique token. Once the token is generated correctly it is used to authenticate a request.
This is done by setting two HTTP headers on the request:. This prefix should be removed before sending the request to Stream. When dealing with authentication tokens, you should keep in mind that tokens are like passwords.
Never share tokens with untrusted parties. Requests from a back-end application to the Stream API for a specific single resource use Server-Side Authentication to authenticate requests. For server-side authentication, the application should send a token that is signed with the API Secret of the Stream app.A WebResponse that contains the response from the Internet resource. TransferEncoding is set to a value and SendChunked is false.
The ContentLength is greater than zero, but the application does not write all of the promised data. The request cache validator indicated that the response for this request can be served from the cache; however, this request includes data to be sent to the server. Requests that send data must not use the cache.
This exception can occur if you are using a custom cache validator that is incorrectly implemented. Abort was previously called. The GetResponse method returns a WebResponse object that contains the response from the Internet resource. A ProtocolViolationException is thrown in several cases when the properties set on the HttpWebRequest class are conflicting. This exception occurs if an application tries to send chunked to a server that only supports HTTP 1.
This exception occurs if an application tries to send data without setting the ContentLength property or the SendChunked is false when buffering is disabled and on a keepalive connection the KeepAlive property is true. You must call the Close method to close the stream and release the connection. Failure to do so may cause your application to run out of connections.
When using the POST method, you must get the request stream, write the data to be posted, and close the stream. This method blocks waiting for content to post; if there is no time-out set and you do not provide content, the calling thread blocks indefinitely. Multiple calls to GetResponse return the same response object; the request is not reissued.
Your application cannot mix synchronous and asynchronous methods for a particular request. If you call the GetRequestStream method, you must use the GetResponse method to retrieve the response. If a WebException is thrown, use the Response and Status properties of the exception to determine the response from the server.
Http Web Request. Net Assembly: System. Returns a response from an Internet resource. Caution You must call the Close method to close the stream and release the connection. Note Multiple calls to GetResponse return the same response object; the request is not reissued. Note Your application cannot mix synchronous and asynchronous methods for a particular request.
The dark mode beta is finally here. Change your preferences any time. Stack Overflow for Teams is a private, secure spot for you and your coworkers to find and share information. With a RESTful service you can create, read, update, and delete resources.
This all works well when you're dealing with something like a database assets - but how does this translate to streaming data? Or does it? For instance, in the case of video, it seems silly to treat each frame as resource that I should query one at a time. Rather I would set up a socket connection and stream a series of frames.
But does this break the RESTful paradigm? What if I want to be able to rewind or fast forward the stream? Is this possible within the RESTful paradigm? As a matter of implementation, I am getting ready to create such a streaming data service, and I want to make sure I'm doing it the "best way".
I'm sure this problem's been solved before. Can someone point me to good material? I did not manage to find materials about truly RESTful streaming - it seems that results are mostly about delegating streaming to another service which is not a bad solution. So I'll do my best to tackle it myself - note that streaming is not my domain, but I'll try to add my 2 cents. In the aspect of streaming, I think that we need to separate the problem into two independent parts:. Access to media resources This is pretty straightforward and can be handled in a clean and RESTful way.
Even though this might work, I agree with you that it's not a viable option. The latter option - streaming via HTTP - might not be as efficient as the above, but it's definitely possible. Technically, it's not that different than allowing access to any form of binary content via HTTP.
In this case our API would provide a link to the binary resource accessible via HTTP, and also advises us about the size of the resource:.
One option is for the client to download the whole resource - HTTP progressive download. A cleaner alternative would be for the client to access the resource in chunks by utilizing HTTP Range headers.
For fetching the second KB chunk of a file that is 1MB large, the client request would then look like this:. A server which supports ranges would then respond with the Content-Range headerfollowed by the partial representation of the resource:. Learn more. How do streaming resources fit within the RESTful paradigm? Ask Question. Asked 9 years, 2 months ago. Active 2 years, 1 month ago.
Viewed 44k times. Tim Cooper k 34 34 gold badges silver badges bronze badges.There are many dichotomies in the world of API design. It seems for each architectural choice there exists an opposite solution purpose-built for a specific application.
These two options are fundamentally different in a variety of ways, not the least of which is their essential relationship between the client and the server. For this reason, the architectures bear comparison, and the solutions present in each field bear some further discussion. Keep in mind that much of this piece will be using generalities and there are bound to be edge cases.
Consider this a general overview of the standard use cases behind REST and Streaming APIsas well as the standard architectures, approaches, and natures one would expect from each. By design, RESTful APIs separate the concerns held by the client and by the server, allowing for each to evolve independently of one another.
The API itself holds no client context on the server beyond that relevant to the immediate request and the information needed to authenticate the client. They can store data that has been previously requested, and then serve that data upon demand. In theory, they should also be able to extend their capabilities temporarily through the use of executable extensions — this is completely optional, however.
Finally, REST APIs should be somewhat obfuscated to the end user, with a layered API system of intermediaries and primary servers being able to carry out instruction without exposing their position in the hierarchy to the end user.
This is largely a requirement to provide for scalability and load balancingalthough there are additional benefits to this approach — namely, increases in security by reducing the visibility of attack vectors, the ability to distribute and share cached information over differently geolocated caches, and redundancy in server function to ensure optimum uptime.Watch live: President Trump and Coronavirus Task Force hold briefing at the White House
Streaming APIs, on the other hand, send updates to the client when events occur. In its most basic state, Streaming APIs invert the conversational nature of RESTwhere a request is made and a response is given, and instead has the server send information to a client when an update is ready. While the client can, in theory, request an update, the streaming server should preempt this with updates as ready.
Without storing state in some form, the Streaming API cannot properly contextualize the data relationship with the requesting client. In other words, clients typically open persistent connections with the streaming server in question. While this connection certainly has a limited lifespan, it is during this connection that the pushed content is delivered.
Thus, when a request is made, in some applications such as GraphQLthe format or content type can be stated as an expected supported variable. Streaming APIs, on the other hand, typically have a strictly limited response format.
In other words, you get what the server provides.
Scripted REST API example - streaming vs object serialization
Something is requested, something is done, and then something is sent in return. This exchange is a conversation — for this reason, REST architecture is usually designed around the idea of providing highly modular micro-solutions for given use cases. The underpinning architecture behind the entirety of REST is the modular web server. This may take the form a physical servers or virtual servers, but ultimately, the idea of nodes that can quickly spin up or spin down is very core to the RESTful microservice-heavy landscape that dominates most of the enterprise REST landscape.
These servers also have a very specific requirement — they must be able to support both the bandwidth of requests and the resultant bandwidth of custom output required. Even with lightweight solutions, this is still a fundamental requirement of the REST server node — it must be able to converse.
JAX RS: Streaming a Response using StreamingOutput
While this is not unique to REST, many architectural choices have been made to support the use of these codes and to have them trigger certain actions within RESTful implementations.
REST requires high-bandwidth request and response-oriented servers — streaming APIs, on the other hand, utilize event brokers to manage this interaction. What the software needs to support is a simple method of storing the status of an open connection or a long-term requester, and then send the same information globally to each group of users.