From be5cb6f55141cd42c9b486c33815b0acbe8ea556 Mon Sep 17 00:00:00 2001 From: stremovsky Date: Thu, 19 Dec 2019 14:26:07 +0200 Subject: [PATCH] Add shared record section --- API.md | 77 ++++++++++++++++++++++++++------------------- create-test-user.sh | 36 ++++++++++----------- 2 files changed, 63 insertions(+), 50 deletions(-) diff --git a/API.md b/API.md index cee2a90..638c6a5 100644 --- a/API.md +++ b/API.md @@ -162,6 +162,8 @@ mix is with profile data. For example shipping information. This API is used to create new user app record and if the request is successful it returns `{"status":"ok"}`. Subminiting several times for the same user and app will overwrite previous value. +You can send app data as JSON POST or as regular POST parameters. + ### Example: ``` @@ -211,7 +213,7 @@ You can use **Session API** to store and manage user sessions. For example sessi You can use **session token** generated in your application logs instead of clear text user IP, cookies, etc... This information is is considered now as PII. -Sesion generation API is flexible and you can push any data you wish to save in session record. It can be: +Session generation API is flexible and you can push any data you wish to save in session record. It can be: user ip, mobile device info, user agent, etc... Each session record has an expiration period. When the record it is expired, it is automatically deleted. @@ -294,7 +296,7 @@ curl -s http://localhost:3000/v1/session/phone/4444 \ ## User consent management API One of the GDPR requirements is the storage of user consent. For example, your customer must approve to receive -email marketing information. Data bunker provides an API for user consent management. +email marketing information. Data bunker provides an API for user consent storage and management. When working with consent, Data bunker is using `brief` value as a consent name. It is unique per user, short consent id. Allowed chars are [a-z0-9\-] . Max 64 chars. @@ -394,48 +396,59 @@ curl --header "X-Bunker-Token: $XTOKEN" -XGET \ --- -## Passwordless tokens API +## Shareable record API -| Resource / HTTP method | POST (create) | GET (read) | PUT (update) | DELETE (delete) | -| ---------------------- | ----------------- | ------------- | ---------------- | ---------------- | -| /v1/xtoken/{token} | Create new record | Error | Error | Error | -| /v1/xtoken/:xtoken | Error | Get data | Error | Error | +Sometimes you want to share part of user profile, part fo app data or a part of session details +with a partner or to save in logs. Data Bunker provides an easy API to do it. - router.POST("/v1/xtoken/{token}", e.userNewToken) - router.GET("/v1/xtoken/:xtoken", e.userCheckToken) +Each record created has an expiration time. Access to the record data is open to anyone without +any access token or without a password. + +| Resource / HTTP method | POST (create) | GET (read) | PUT (update) | DELETE (delete) | +| ------------------------------ | ----------------- | ------------ | ------------- | ---------------- | +| /v1/sharedrecord/token/{token} | Create new record | Error | Error | Error | +| /v1/get/{record} | Error | Get data | Error | Error | ---- +## Create shared record request +### `POST /v1/sharedrecord/token/{token}` +### Explanation -## Shareable record identity API +This API is used to create shared record that is referencing other object in the database (user, user-app, session). +It returns `{record}` token on success. -| Resource / HTTP method | POST (create) | GET (read) | PUT (update) | DELETE (delete) | -| ---------------------- | ----------------- | ------------- | ---------------- | ---------------- | -| /v1/record/{token} | Create new record | Error | Error | Error | -| /v1/record/{record} | Error | Get data | Error | Error | +You can user this token, for example when you need to 3rd party system as a user identity. +### POST Body Format ---- +POST Body can contain regular form data or JSON. Expected optional values are `message`, `status`. +| Parameter | Required | Description | +| ----------- | --------- | ---------------------------------------------------- | +| app | No | Application name. | +| partner | No | Partner name. For example coralogix. | +| expiration | No | Record expiration time. | +| session | No | Session record token. | +| fields | No | List of records to extract. Separated by commas. | -### 3rd party logging - -Instead of maintaining internal logs, a lot of companies are using 3rd party logging facility like logz or coralogix or something else. -To improve adherence to GDPR, we build a special feature - generate specific session id for such 3rd party service. - -When using these uuids in external systems, you basically **pseudonymise personal data**. In addition, in accordance with GDPR Article 5: -**Principles relating to processing of personal data**. Personal data shall be: (c) -adequate, relevant and limited to what is necessary in relation to the purposes for which they are processed (‘**data minimisation**’); - -Here is a command to do it: +### Example: ``` -curl -d 'ip=user@example.com' \ - -d 'user-agent=mozila' \ - -d 'partner=coralogix' \ - -d 'expiration=7d'\ - https://bunker.company.com/gensession/DAD2474A-E9A7-4BA7-BFC2-C4506880198E +curl -s http://localhost:3000/v1/sharedrecord/token/$TOKEN \ + -H "X-Bunker-Token: $XTOKEN" -H "Content-Type: application/json" \ + -d '{"app":"shipping","fields":"address"}' +{"status":"ok","record":"db90efc7-48fe-9709-891d-a8b295881a9a"} ``` -It will generate a new token, that you can now pass to 3rd party system as a user id. +## Get record value. +### `GET /v1/get/{record}` + +Return record value. + +### Example: + +``` +curl -s http://localhost:3000/v1/get/$RECORD +{"status":"ok","app":"shipping","data":{"address":"221B Baker Street"}} +``` diff --git a/create-test-user.sh b/create-test-user.sh index 9d6084f..15bd4d2 100755 --- a/create-test-user.sh +++ b/create-test-user.sh @@ -8,12 +8,12 @@ fi echo "Creating user." RESULT=`curl -s http://localhost:3000/v1/user \ - -H "X-Bunker-Token: "$XTOKEN -H "Content-Type: application/json" \ + -H "X-Bunker-Token: $XTOKEN" -H "Content-Type: application/json" \ -d '{"fname":"Test","lname":"Account","email":"test@paranoidguy.com","phone":"4444"}'` STATUS=`echo $RESULT | jq ".status" | tr -d '"'` if [ "$STATUS" == "error" ]; then echo "Error to create user, trying to lookup by email." - RESULT=`curl -s http://localhost:3000/v1/user/email/test@paranoidguy.com -H "X-Bunker-Token: "$XTOKEN` + RESULT=`curl -s http://localhost:3000/v1/user/email/test@paranoidguy.com -H "X-Bunker-Token: $XTOKEN"` STATUS=`echo $RESULT | jq ".status" | tr -d '"'` fi if [ "$STATUS" == "error" ]; then @@ -25,22 +25,22 @@ TOKEN=`echo $RESULT | jq ".token" | tr -d '"'` echo "User token is $TOKEN" RESULT=`curl -s http://localhost:3000/v1/userapp/token/$TOKEN/shipping \ - -H "X-Bunker-Token: "$XTOKEN -H "Content-Type: application/json" \ + -H "X-Bunker-Token: $XTOKEN" -H "Content-Type: application/json" \ -d '{"country":"UK","city":"London","address":"221B Baker Street","postcode":"12345","status":"new"}'` echo "User shipping record created, status $RESULT" RESULT=`curl -s http://localhost:3000/v1/userapp/token/$TOKEN/shipping -XPUT \ - -H "X-Bunker-Token: "$XTOKEN -H "Content-Type: application/json" \ + -H "X-Bunker-Token: $XTOKEN" -H "Content-Type: application/json" \ -d '{"status":"delivered"}'` echo "User shipping record updated, status $RESULT" RESULT=`curl -s http://localhost:3000/v1/userapp/token/$TOKEN/shipping \ - -H "X-Bunker-Token: "$XTOKEN` + -H "X-Bunker-Token: $XTOKEN"` echo "User shipping record ready, status $RESULT" RESULT=`curl -s http://localhost:3000/v1/sharedrecord/token/$TOKEN \ - -H "X-Bunker-Token: "$XTOKEN -H "Content-Type: application/json" \ + -H "X-Bunker-Token: $XTOKEN" -H "Content-Type: application/json" \ -d '{"app":"shipping","fields":"address"}'` echo "Shared record created, status $RESULT" RECORD=`echo $RESULT | jq ".record" | tr -d '"'` @@ -50,39 +50,39 @@ RESULT=`curl -s http://localhost:3000/v1/get/$RECORD` echo "Get shared record (no password/access token): $RESULT" RESULT=`curl -s http://localhost:3000/v1/userapp/token/$TOKEN \ - -H "X-Bunker-Token: "$XTOKEN -H "Content-Type: application/json"` + -H "X-Bunker-Token: $XTOKEN" -H "Content-Type: application/json"` echo "View list of all user apps $RESULT" RESULT=`curl -s http://localhost:3000/v1/userapps \ - -H "X-Bunker-Token: "$XTOKEN -H "Content-Type: application/json"` + -H "X-Bunker-Token: $XTOKEN" -H "Content-Type: application/json"` echo "View list of all apps $RESULT" RESULT=`curl -s http://localhost:3000/v1/consent/token/$TOKEN/send-sms -XPOST \ - -H "X-Bunker-Token: "$XTOKEN -H "Content-Type: application/json"` + -H "X-Bunker-Token: $XTOKEN" -H "Content-Type: application/json"` echo "Enable consent send-sms for user by token: $RESULT" RESULT=`curl -s http://localhost:3000/v1/consent/email/test@paranoidguy.com/send-sms2 -XPOST \ - -H "X-Bunker-Token: "$XTOKEN -H "Content-Type: application/json"` + -H "X-Bunker-Token: $XTOKEN" -H "Content-Type: application/json"` echo "Enable consent send-sms for user by email: $RESULT" RESULT=`curl -s http://localhost:3000/v1/consent/phone/4444/send-sms2 -XDELETE \ - -H "X-Bunker-Token: "$XTOKEN -H "Content-Type: application/json"` + -H "X-Bunker-Token: $XTOKEN" -H "Content-Type: application/json"` echo "Withdraw consent send-sms for user by phone: $RESULT" RESULT=`curl -s http://localhost:3000/v1/consent/token/$TOKEN/send-sms \ - -H "X-Bunker-Token: "$XTOKEN -H "Content-Type: application/json"` + -H "X-Bunker-Token: $XTOKEN" -H "Content-Type: application/json"` echo "View this specific consent only: $RESULT" RESULT=`curl -s http://localhost:3000/v1/consent/token/$TOKEN \ - -H "X-Bunker-Token: "$XTOKEN -H "Content-Type: application/json"` + -H "X-Bunker-Token: $XTOKEN" -H "Content-Type: application/json"` echo "View all user consents: $RESULT" RESULT=`curl -s http://localhost:3000/v1/consents/send-sms \ - -H "X-Bunker-Token: "$XTOKEN -H "Content-Type: application/json"` + -H "X-Bunker-Token: $XTOKEN" -H "Content-Type: application/json"` echo "View all users with send-sms consent on: $RESULT" RESULT=`curl -s http://localhost:3000/v1/session/token/$TOKEN -XPOST \ - -H "X-Bunker-Token: "$XTOKEN -H "Content-Type: application/json" \ + -H "X-Bunker-Token: $XTOKEN" -H "Content-Type: application/json" \ -d '{"clientip":"1.1.1.1","x-forwarded-for":"2.2.2.2"}'` echo "Create session 1: $RESULT" @@ -90,14 +90,14 @@ SESSION=`echo $RESULT | jq ".session" | tr -d '"'` echo $SESSION RESULT=`curl -s http://localhost:3000/v1/session/email/test@paranoidguy.com -XPOST \ - -H "X-Bunker-Token: "$XTOKEN -H "Content-Type: application/json" \ + -H "X-Bunker-Token: $XTOKEN" -H "Content-Type: application/json" \ -d '{"clientip":"1.1.1.1","x-forwarded-for":"2.2.2.2","info":"email"}'` echo "Create session 2: $RESULT" RESULT=`curl -s http://localhost:3000/v1/session/session/$SESSION \ - -H "X-Bunker-Token: "$XTOKEN -H "Content-Type: application/json"` + -H "X-Bunker-Token: $XTOKEN" -H "Content-Type: application/json"` echo "Get session 1: $RESULT" RESULT=`curl -s http://localhost:3000/v1/session/phone/4444 \ - -H "X-Bunker-Token: "$XTOKEN -H "Content-Type: application/json"` + -H "X-Bunker-Token: $XTOKEN" -H "Content-Type: application/json"` echo "Get sessions: $RESULT"