Skip to content

Deprecated API transition guide. #363

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
102 changes: 102 additions & 0 deletions API_TRANSITION_GUIDE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,102 @@
## Deprecated API Transition Guide

When APIs are deprecated, the following guide will show how to transition from removed APIs to the new ones


### Upgrading From 3.x to 4.0

In the 3.2.0 release, a few APIs were set to be deprecated in the 4.0 release. With the release of 4.0.0, those APIs have been removed.

#### Receiever

The `Receiver` class has been removed.

`Receiver.accept` should be transitioned to `HTTP.toEvent`

Here is an example of what a `HTTP.toEvent` might look like using Express.js

```js
const app = require("express")();
const { HTTP } = require("cloudevents");

app.post("/", (req, res) => {
// body and headers come from an incoming HTTP request, e.g. express.js
const receivedEvent = HTTP.toEvent({ headers: req.headers, body: req.body });
console.log(receivedEvent);
});
```

#### Emitter

`Emit.send` should be transitioned to `HTTP.binary` for binary events and `HTTP.structured` for structured events

`Emit.send` would use axios to emit the events. Since this now longer available, you are free to choose your own transport protocol.

So for axios, it might look something like this:

```js
const axios = require('axios').default;
const { HTTP } = require("cloudevents");


const ce = new CloudEvent({ type, source, data })
const message = HTTP.binary(ce); // Or HTTP.structured(ce)

axios({
method: 'post',
url: '...',
data: message.body,
headers: message.headers,
});
```

You may also use the `emitterFor()` function as a convenience.

```js
const axios = require('axios').default;
const { emitterFor, Mode } = require("cloudevents");

function sendWithAxios(message) {
// Do what you need with the message headers
// and body in this function, then send the
// event
axios({
method: 'post',
url: '...',
data: message.body,
headers: message.headers,
});
}

const emit = emitterFor(sendWithAxios, { mode: Mode.BINARY });
emit(new CloudEvent({ type, source, data }));
```

You may also use the `Emitter` singleton

```js
const axios = require("axios").default;
const { emitterFor, Mode, CloudEvent, Emitter } = require("cloudevents");

function sendWithAxios(message) {
// Do what you need with the message headers
// and body in this function, then send the
// event
axios({
method: "post",
url: "...",
data: message.body,
headers: message.headers,
});
}

const emit = emitterFor(sendWithAxios, { mode: Mode.BINARY });
// Set the emit
Emitter.on("cloudevent", emit);

...
// In any part of the code will send the event
new CloudEvent({ type, source, data }).emit();

// You can also have several listener to send the event to several endpoint
```
5 changes: 5 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -138,6 +138,11 @@ There are a few trivial example applications in
[the examples folder](https://github.com/cloudevents/sdk-javascript/tree/main/examples).
There you will find Express.js, TypeScript and Websocket examples.


### API Transition Guide

[Guide Link](./API_TRANSITION_GUIDE.md)

## Supported specification features

| Core Specification | [v0.3](https://github.com/cloudevents/spec/blob/v0.3/spec.md) | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/spec.md) |
Expand Down