2

I'm trying to develop rest api for the first time. And looking to loopback references that uses change stream for the resources like /resources/change-stream with the GET and POST methods.

I have visited this post which indicates differences between rest api and streaming api.

While the loopback is providing it in rest api, I think. What is it and what it does. Can you please explain it to me in a way that you're making clear to me (for a six years old child). Because, I am developing REST API for the first time in my own. So, I would like to understand step by step if possible like what should I have in the postman. Should I use the url like '/api/resources/change-stream?_format=event-stream along with application/json content-type or just /api/resources/change-stream would be fine.

It would be great example if you could provide me some real example so that I can develop it trying in my own application.

PS: It's perfectly fine to me whichever language (Node.js, Python, Ruby, PHP) you'd choose to provide answer with some examples.

Subhanshuja
  • 390
  • 1
  • 3
  • 20
Bhojendra Rauniyar
  • 83,432
  • 35
  • 168
  • 231
  • 1
    There's no need to add a bunch of tags that are unrelated to your question. Just because it is possible to develop a REST API in a given language doesn't mean you need to tag your question with that language. – anothermh May 09 '19 at 19:09
  • 1
    Could you describe the intended purpose of your API? You say that you are developing a REST API, but it sounds like you *want* a stream API. The two aren't exactly exclusive, and you can even create a sort of event stream API endpoint for your REST API as I described in my answer. However, depending on your intent, you can make architectural decisions. It almost sounds like you think a stream API is a requirement for a REST API which isn't the case. – zero298 May 09 '19 at 19:36
  • 1
    @zero298 I was thinking something else badly. Thanks for your confirmation. I'm still waiting for others. I really appreciate your answer. – Bhojendra Rauniyar May 09 '19 at 19:51

1 Answers1

3

If I had to guess, it sounds like a 1-way long polling where you leave a long running, open request to a server that will fulfill the request when an event happens. If the request times out, don't worry about it, send another and leave it open. When the request is fulfilled with an event, immediately fire another request so that you can receive the next event.

Since the document on the other end of the API is still (probably) a JSON document, you should keep that mime. However, you aren't limited in what you can send back as an event type; if you want to send back XML or YAML, do so and set that mime. The "stream" is just a convention mechanism.

As far as your application is concerned and from a REST perspective, it just takes a while for the event that you are trying to get to be provided to you and it has a high chance of failure. But I wouldn't look at this from a REST perspective, REST is just convention, don't let it tie you down.

Alternatively, long-polling should probably be replaced by something like a WebSocket as it provides a much easier API (in my opinion) and doesn't seem as hacky as long-polling.

If you're trying to ask, "how do I tell a RESTful consumer that my API is a 'stream' API", there is not point. Again, as far as REST is concerned, the https://example.com/api/events/ endpoint refers to a JSON type document that changes a lot, takes a long time to receive, and "fails" often (if the events you generate don't fire a lot).

zero298
  • 25,467
  • 10
  • 75
  • 100
  • Thanks for your answer. Do you mean if I also use websocket then I don't need to provide such endpoint? BTW, linked post seems to be a good read to me. Thanks again. – Bhojendra Rauniyar May 09 '19 at 19:06
  • @BhojendraRauniyar You don't have to unless whatever client you are serving doesn't support something like WebSocket. Consider the [Socket.IO](https://socket.io/) library. It deals with pull/push messaging between client and server but has support for Flash, WebSocket, and long-polling connectivity depending on what is supported by the client. What is your target? There is no reason you can't support a RESTful interface for this while **also** having a WebSocket endpoint. – zero298 May 09 '19 at 19:39