Skip to content

Commit fb1a5f2

Browse files
Yaniv Ben HemoYaniv Ben Hemo
Yaniv Ben Hemo
authored and
Yaniv Ben Hemo
committed
readme change
1 parent a2f5fcc commit fb1a5f2

File tree

1 file changed

+145
-60
lines changed

1 file changed

+145
-60
lines changed

‎README.md‎

Lines changed: 145 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -85,89 +85,129 @@ Soon.
8585
If you are using Memphis **Open-Source** version, please make sure your 'REST gateway' component is exposed either through localhost or public IP.<br><br>
8686
If you are using Memphis **Cloud**, it is already in.
8787

88-
### Authenticate
88+
### 1. Create a JWT token
8989

90-
First, you have to authenticate to get a JWT token.\
91-
The default expiration time is 15 minutes.
90+
Please create a JWT token, which will be part of each produce/consume request. For authentication purposes.
9291

93-
#### Example:
92+
* The generated JWT will encapsulate all the needed information for the broker to ensure the requester is authenticated to communicate with Memphis.
93+
* JWT token (by design) has an expiration time. Token refreshment can take place progrematically, but as it is often used to integrate memphis with other systems which are not supporting JWT refreshment, a workaround to overcome it would be to set a very high value in the `token_expiry_in_minutes`.
94+
* The default expiry time is 15 minutes.
9495

95-
* Cloud: Your REST GW URL can be found within a station->code examples
96-
* OS: The REST GW will be deploy by default, and as with any other service, should be exposed based on your deployment type.
96+
**Cloud (Using body params)**<br>
97+
* Please replace the [Cloud], [Region], Username, Password, and Account ID with your parameters.
98+
```bash
99+
curl --location --request POST 'https://[Cloud]-[Region].restgw.cloud.memphis.dev/auth/authenticate' \
100+
--header 'Content-Type: application/json' \
101+
--data-raw '{
102+
"username": "CLIENT_TYPE_USERNAME",
103+
"password": "CLIENT_TYPE_PASSWORD",
104+
"account_id": 123456789,
105+
"token_expiry_in_minutes": 6000000,
106+
"refresh_token_expiry_in_minutes": 100000
107+
}'
108+
```
109+
110+
**Cloud (Using query params)**<br>
111+
* Please replace the [Cloud], [Region], Username, Password, and Account ID with your parameters.
112+
```bash
113+
curl --location --request POST 'https://[Cloud]-[Region].restgw.cloud.memphis.dev/auth/authenticate?accountId=123456789' \
114+
--header 'Content-Type: application/json' \
115+
--data-raw '{
116+
"username": "CLIENT_TYPE_USERNAME",
117+
"password": "CLIENT_TYPE_PASSWORD",
118+
"token_expiry_in_minutes": 6000000,
119+
"refresh_token_expiry_in_minutes": 100000
120+
}'
121+
```
97122

123+
**Open-source**
98124
```bash
99125
curl --location --request POST 'https://REST_GW_URL:4444/auth/authenticate' \
100126
--header 'Content-Type: application/json' \
101127
--data-raw '{
102-
"username": "root",
103-
// "connection_token": "memphis", // OS Only: In case the chosen auth method is connection_token
104-
"password": "memphis, // OS + Cloud: client-type user password
105-
"account_id": 123456789, // Cloud only, in case you don't have the ability to set this field as a body param you can add it as a query string param, for example: https://<REST-GW-ADDRESS>/auth/authenticate?accountId=123456789
106-
"token_expiry_in_minutes": 60,
107-
"refresh_token_expiry_in_minutes": 10000092
128+
"username": "CLIENT_TYPE_USERNAME",
129+
"password": "CLIENT_TYPE_PASSWORD,
130+
"token_expiry_in_minutes": 6000000,
131+
"refresh_token_expiry_in_minutes": 100000
108132
}'
109133
```
110134

111135
Expected output:&#x20;
112136

113137
```JSON
114-
{"expires_in":3600000,"jwt":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2NzQ3MTg0MjV9._A-fRI78fPPHL6eUFoWZjp21UYVcjXwGWiYtacYPZR8","jwt_refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjIyNzQ3MjAzNDV9.d89acaIr4CaBp7csm-jmJv0J45YrD_slvlEOKu2rs7Q","refresh_token_expires_in":600005520000}
138+
{"expires_in":3600000,"jwt":"eyJhbGciO***************nR5cCI6IkpXVCJ9.eyJleHAiOjE2NzQ3MTg0MjV9._A************UFoWZjp21UYVcjXwGWiYtacYPZR8","jwt_refresh_token":"eyJhbGciOiJIUzI1N***************kpXVCJ9.eyJleHAiOjIy*********************7csm-jmJv0J45YrD_slvlEOKu2rs7Q","refresh_token_expires_in":600005520000}
115139
```
140+
<hr>
116141

117-
#### Parameters
118-
119-
`username`: Memphis application-type username\
120-
`connection_token`: Memphis application-type connection token\
121-
`token_expiry_in_minutes`: Initial token expiration time.\
122-
`refresh_token_expiry_in_minutes`: When should
142+
**Refresh a token**
123143

124-
### Refresh Token
144+
Before the JWT token expires or after an authentication failure, you must call the refresh procedure and get a new token. The refresh JWT token is valid by default for 5 hours.
125145

126-
Before the JWT token expires, you must call the refresh token to get a new one, or after authentication failure.\
127-
The refresh JWT is valid by default for 5 hours.
128-
129-
#### Example:
146+
**Cloud**<br>
147+
* Please replace the [Cloud], [Region], Username, and Password with your parameters.
148+
```bash
149+
curl --location --request POST 'https://[Cloud]-[Region].restgw.cloud.memphis.dev/auth/refreshToken' \
150+
--header 'Content-Type: application/json' \
151+
--data-raw '{
152+
"jwt_refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjIyNz*******************VPSjtU4x02z_jbWhu5pIByhCRh6FU8",
153+
"token_expiry_in_minutes": 60000000,
154+
"refresh_token_expiry_in_minutes": 10000000
155+
}'
156+
```
130157

158+
**Open-source**
131159
```bash
132-
curl --location --request POST 'rest_gateway:4444/auth/refreshToken' \
160+
curl --location --request POST 'https://REST_GW_URL:4444/auth/refreshToken' \
133161
--header 'Content-Type: application/json' \
134162
--data-raw '{
135-
"jwt_refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjIyNzQ3MjA2NjB9.Furfr5EZlBlglVPSjtU4x02z_jbWhu5pIByhCRh6FU8",
136-
"token_expiry_in_minutes": 60,
137-
"refresh_token_expiry_in_minutes": 10000092
163+
"jwt_refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjIyNz*******************VPSjtU4x02z_jbWhu5pIByhCRh6FU8",
164+
"token_expiry_in_minutes": 60000000,
165+
"refresh_token_expiry_in_minutes": 10000000
138166
}'
139167
```
140168

141169
Expected output:
142170

143171
```json
144-
{"expires_in":3600000,"jwt":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2NzQ3MTg3NTF9.EO5ersr0kQxQNRI0XlbqzOryt-F1-MmFGXRKn2sM8Yw","jwt_refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjIyNzQ3MjA2NzF9.E621wF_ieC-9rq4IgrsqYMPApAPS8YDgkT8R-69-Y5E","refresh_token_expires_in":600005520000}
172+
{"expires_in":3600000,"jwt":"eyJhb**************5cCI6IkpXVCJ9.eyJleHAiOjE2NzQ3MTg3N*******************F1-MmFGXRKn2sM8Yw","jwt_refresh_token":"eyJhbGciOiJIUzI*****************IkpXVCJ9.eyJleHAiOjIyNz***********************grsqYMPApAPS8YDgkT8R-69-Y5E","refresh_token_expires_in":600005520000}
145173
```
174+
<hr>
146175

147-
### Produce a single message
176+
### 2. Produce a single message
148177

149-
Attach the JWT token to every request.\
150-
JWT token as '`Bearer`' as a header.
151-
152-
#### Supported content types:
178+
**Supported content types:**
153179

154180
* text
155181
* application/json
156182
* application/x-protobuf
157183

158-
#### Example:
184+
185+
**Cloud (Using body params)**
186+
* Please replace the [Cloud], [Region], JWT token (right after `Bearer`) with your parameters.
187+
159188

160189
```bash
161-
curl --location --request POST 'rest_gateway:4444/stations/<station_name>/produce/single' \
162-
--header 'Authorization: Bearer eyJhbGciOiJIU**********.e30.4KOGRhUaqvm-qSHnmMwX5VrLKsvHo33u3UdJ0qYP0kI' \
190+
curl --location --request POST 'https://[Cloud]-[Region].restgw.cloud.memphis.dev/stations/STATION_NAME/produce/single' \
191+
--header 'Authorization: Bearer eyJhbGciOiJIU**********.e30.4KOGR**************VrLKsvHo33u3UdJ0qYP0kI' \
163192
--header 'Content-Type: application/json' \
164193
--data-raw '{"message": "New Message"}'
165194
```
166195

167-
#### If you don't have the option to add the authorization header, you can send the JWT via query parameters:
196+
**Cloud (Using query params)**
197+
* Please replace the [Cloud], [Region], JWT token with your parameters.
168198

169199
```bash
170-
curl --location --request POST 'rest_gateway:4444/stations/<station_name>/produce/single?authorization=eyJhbGciOiJIU**********.e30.4KOGRhUaqvm-qSHnmMwX5VrLKsvHo33u3UdJ0qYP0kI' \
200+
curl --location --request POST 'https://[Cloud]-[Region].restgw.cloud.memphis.dev/stations/STATION_NAME/produce/single?authorization=eyJhbGciOiJIU**********.e30.4KOLKsvHo33u3UdJ0qYP0kI' \
201+
--header 'Content-Type: application/json' \
202+
--data-raw '{"message": "New Message"}'
203+
```
204+
205+
**Open-source**
206+
* Please replace the JWT token (right after `Bearer`) with your parameter.
207+
208+
```bash
209+
curl --location --request POST 'rest_gateway:4444/stations/STATION_NAME/produce/single' \
210+
--header 'Authorization: Bearer eyJhbGciOiJIU**********.e30.4KOGRhUaqvmUdJ0qYP0kI' \
171211
--header 'Content-Type: application/json' \
172212
--data-raw '{"message": "New Message"}'
173213
```
@@ -178,26 +218,53 @@ Expected output:
178218
{"error":null,"success":true}
179219
```
180220

181-
#### Error Example:
221+
Schema error example:
182222

183223
```json
184224
{"error":"Schema validation has failed: jsonschema: '' does not validate with file:///Users/user/memphisdev/memphis-rest-gateway/123#/required: missing properties: 'field1', 'field2', 'field3'","success":false}
185225
```
186226

187-
### Produce a batch of messages&#x20;
188-
189-
Attach the JWT token to every request.\
190-
JWT token as '`Bearer`' as a header.
227+
<hr>
191228

192-
#### Supported content types:
229+
### 3. Produce a batch of messages
230+
**Supported content types:**
193231

194232
* application/json
195233

196-
#### Example:
234+
**Cloud (Using body params)**
235+
* Please replace the [Cloud], [Region], JWT token (right after `Bearer`) with your parameters.
236+
197237

198238
```bash
199-
curl --location --request POST 'rest_gateway:4444/stations/<station_name>/produce/batch' \
200-
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.e30.4KOGRhUaqvm-qSHnmMwX5VrLKsvHo33u3UdJ0qYP0kI' \
239+
curl --location --request POST 'https://[Cloud]-[Region].restgw.cloud.memphis.dev/stations/STATION_NAME/produce/batch' \
240+
--header 'Authorization: Bearer eyJhbGciOiJIU**********.e30.4KOGR**************VrLKsvHo33u3UdJ0qYP0kI' \
241+
--header 'Content-Type: application/json' \
242+
--data-raw '[
243+
{"message": "x"},
244+
{"message": "y"},
245+
{"message": "z"}
246+
]'
247+
```
248+
249+
**Cloud (Using query params)**
250+
* Please replace the [Cloud], [Region], JWT token with your parameters.
251+
252+
```bash
253+
curl --location --request POST 'https://[Cloud]-[Region].restgw.cloud.memphis.dev/stations/STATION_NAME/produce/batch?authorization=eyJhbGciOiJIU**********.e30.4KOLKsvHo33u3UdJ0qYP0kI' \
254+
--header 'Content-Type: application/json' \
255+
--data-raw '[
256+
{"message": "x"},
257+
{"message": "y"},
258+
{"message": "z"}
259+
]'
260+
```
261+
262+
**Open-source**
263+
* Please replace the JWT token (right after `Bearer`) with your parameter.
264+
265+
```bash
266+
curl --location --request POST 'rest_gateway:4444/stations/STATION_NAME/produce/batch' \
267+
--header 'Authorization: Bearer eyJhbGciOiJIU**********.e30.4KOGRhUaqvmUdJ0qYP0kI' \
201268
--header 'Content-Type: application/json' \
202269
--data-raw '[
203270
{"message": "x"},
@@ -212,33 +279,51 @@ Expected output:
212279
{"error":null,"success":true}
213280
```
214281

215-
#### Error Examples:
282+
Schema error example:
216283

217284
```json
218285
{"errors":["Schema validation has failed: jsonschema: '' does not validate with file:///Users/user/memphisdev/memphis-rest-gateway/123#/required: missing properties: 'field1'","Schema validation has failed: jsonschema: '' does not validate with file:///Users/user/memphisdev/memphis-rest-gateway/123#/required: missing properties: 'field1'"],"fail":2,"sent":1,"success":false}
219286
```
220-
### Consume a batch of messages&#x20;
221287

222-
Attach the JWT token to every request.\
223-
JWT token as '`Bearer`' as a header.
288+
<hr>
289+
224290

225-
The messages are auto acknowledged by the rest gateway.
291+
### 4. Consume a batch of messages&#x20;
226292

227-
#### Supported content types:
293+
To avoid reading the same message twice and reduce network traffic for an ack per message, which is not scalable, messages are auto-acknowledged by the rest gateway.
294+
295+
**Supported content types:**
228296

229297
* application/json
230298

231-
#### Example:
299+
**Cloud (Using body params)**
300+
* Please replace the [Cloud], [Region], JWT token (right after `Bearer`) with your parameters.
301+
302+
303+
```bash
304+
curl --location --request POST 'https://[Cloud]-[Region].restgw.cloud.memphis.dev/stations/STATION_NAME/consume/batch' \
305+
--header 'Authorization: Bearer eyJ***************XVCJ9.e30.4KOGRhUaqvm-qSHnmMw****************' \
306+
--header 'Content-Type: application/json' \
307+
--data-raw '{
308+
"consumer_name": <consumer_name>,
309+
"consumer_group": <consumer_group>,
310+
"batch_size": <batch_size>,
311+
"batch_max_wait_time_ms": <batch_max_wait_time>,
312+
}'
313+
```
314+
315+
**Open-source**
316+
* Please replace the JWT token (right after `Bearer`) with your parameter.
232317

233318
```bash
234-
curl --location --request POST 'rest_gateway:4444/stations/<station_name>/consume/batch' \
319+
curl --location --request POST 'rest_gateway:4444/stations/STATION_NAME/consume/batch' \
235320
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.e30.4KOGRhUaqvm-qSHnmMwX5VrLKsvHo33u3UdJ0qYP0kI' \
236321
--header 'Content-Type: application/json' \
237322
--data-raw '{
238-
"consumer_name": <consumer_name> string required,
239-
"consumer_group": <consumer_group> string defaults to <consumer_name>,
240-
"batch_size": <batch_size> integer defaults to 10,
241-
"batch_max_wait_time_ms": <batch_max_wait_time> integer defaults to 5 secs
323+
"consumer_name": <consumer_name>,
324+
"consumer_group": <consumer_group>,
325+
"batch_size": <batch_size>,
326+
"batch_max_wait_time_ms": <batch_max_wait_time>
242327
}'
243328
```
244329

0 commit comments

Comments
 (0)