Skip to content

Commit 4b19182

Browse files
jbatjbat
committed
NEP-18355 Update docs
1 parent 4cb755f commit 4b19182

File tree

6 files changed

+223
-156
lines changed

6 files changed

+223
-156
lines changed

‎README.md‎

Lines changed: 33 additions & 146 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,12 @@ All ruby classes are namespaced under `Superset::`
88

99
# Installation
1010

11+
## Setup API Credentials
12+
13+
Follow this to [setup your users API creds](https://github.com/rdytech/superset-client/tree/develop/doc/setting_up_personal_api_credentials.md)
14+
15+
Short version is .. copy the `env.sample` to `.env` and add edit values where applicable. Opening a console with `bin/console` will then auto load the `.env` file.
16+
1117
## Docker Setup
1218

1319
Build, bundle and open a ruby console
@@ -18,188 +24,69 @@ docker-compose run --rm app bundle install
1824
docker-compose run --rm app bin/console
1925
```
2026

21-
Run specs
27+
## Setup Locally ( no docker )
28+
29+
Requires Ruby >= 2.6.0
30+
31+
Bundle install and open a ruby console.
2232

2333
```
24-
docker-compose run --rm app rspec
25-
# or
26-
docker-compose run --rm app bash # then run 'bundle exec rspec' from the container.
34+
bundle install
35+
bin/console
2736
```
2837

29-
## Local setup or including in a Ruby/Rails app
38+
## Including in a Ruby app
3039

3140
Add to your Gemfile `gem 'superset'`
3241
And then execute: `bundle install`
3342
Or install it yourself as `gem install superset`
3443

35-
## Setup API Credentials
44+
## Run specs
3645

37-
Follow this doc setup your users API creds [setting_up_personal_api_credentials](https://github.com/rdytech/superset-client/tree/develop/doc/setting_up_personal_api_credentials.md)
46+
```
47+
docker-compose run --rm app rspec
48+
# or
49+
docker-compose run --rm app bash # then run 'bundle exec rspec' from the container.
50+
```
3851

39-
Short version is .. copy the `env.sample` to `.env` and add edit values where applicable. Opening a console with `bin/console` will then auto load the `.env` file.
4052

4153
## Usage
4254

43-
Experiment with the API calls directly by open a pry console using `bin/console`
44-
45-
46-
47-
48-
### API calls
49-
50-
Quickstart examples
55+
Experiment with the API calls directly by open a pry console using `bin/console`.
5156

5257
```ruby
53-
Superset::Database::List.call
54-
Superset::Database::GetSchemas.new(1).list # get schemas for database 1
55-
5658
Superset::Dashboard::List.call
57-
Superset::Dashboard::List.new(title_contains: 'Sales').list
58-
59-
Superset::Dashboard::BulkDelete.new(dashboard_ids: [1,2,3]).perform # Dashboards only ( leaves all charts, datasets in place)
60-
Superset::Dashboard::BulkDeleteCascade.new(dashboard_ids: [1,2,3]).perform # Dashboards and related charts and datasets.
61-
62-
Superset::Sqllab::Execute.new(database_id: 1, schema: 'public', query: 'select count(*) from birth_names').perform
63-
64-
Superset::Dashboard::Export.new(dashboard_id: 1, destination_path: '/tmp').perform
65-
66-
Superset::RouteInfo.new(route: 'dashboard/_info').perform # Get info on an API endpoint .. handy for getting available filters
67-
Superset::RouteInfo.new(route: 'chart/_info').filters # OR just get the filters for an endpoint
6859

6960
superset_class_list # helper method to list all classes under Superset::
70-
61+
sshelp # aliased for superset_class_list
7162
```
7263

73-
### Duplicating Dashboards
74-
75-
Primary motivation behind this library was to use the Superset API to duplicate dashboards, charts, datasets across multiple database connections.
76-
See examples in [Duplicate Dashboards](https://github.com/rdytech/superset-client/tree/develop/doc/duplicate_dashboards.md)
77-
78-
### API Examples with results
79-
80-
Generally classes follow the convention/path of the Superset API strucuture as per the swagger docs.
81-
82-
ref https://superset.apache.org/docs/api/
83-
84-
Limited support for filters is available on some list pages, primarily through param `title_contains`.
85-
Pagination is supported via `page_num` param.
86-
87-
Primary methods across majority of api calls are
88-
- response : the full API response
89-
- result : just the result attribute array
90-
- list : displays a formatted output to console, handy for quick investigation of objects
91-
- call : is a class method to list on Get and List requests
92-
93-
```ruby
94-
# List all Databases
95-
Superset::Database::List.call
96-
# DEBUG -- : Happi: GET https://your-superset-host/api/v1/database/?q=(page:0,page_size:100), {}
97-
+----+------------------------------------+------------+------------------+
98-
| Superset::Database::List |
99-
+----+------------------------------------+------------+------------------+
100-
| Id | Database name | Backend | Expose in sqllab |
101-
+----+------------------------------------+------------+------------------+
102-
| 1 | examples | postgresql | true |
103-
+----+------------------------------------+------------+------------------+
104-
105-
# List database schemas for Database 1
106-
Superset::Database::GetSchemas.new(1).list
107-
# DEBUG -- : Happi: GET https://your-superset-host/api/v1/database/1/schemas/, {}
108-
=> ["information_schema", "public"]
109-
110-
# List dashboards
111-
Superset::Dashboard::List.call
112-
# PAGE_SIZE is set to 100, so get the second set of 100 dashboards with
113-
Superset::Dashboard::List.new(page_num: 1).list
114-
# OR filter by title
115-
Superset::Dashboard::List.new(title_contains: 'Sales').list
116-
# DEBUG -- : Happi: GET https://your-superset-host/api/v1/dashboard/?q=(filters:!((col:dashboard_title,opr:ct,value:'Sales')),page:0,page_size:100), {}
117-
118-
+-----+------------------------------+-----------+--------------------------------------------------------------------+
119-
| Superset::Dashboard::List |
120-
+-----+------------------------------+-----------+--------------------------------------------------------------------+
121-
| Id | Dashboard title | Status | Url |
122-
+-----+------------------------------+-----------+--------------------------------------------------------------------+
123-
| 6 | Video Game Sales | published | https://your-superset-host/superset/dashboard/6/ |
124-
| 8 | Sales Dashboard | published | https://your-superset-host/superset/dashboard/8/ |
125-
+-----+------------------------------+-----------+--------------------------------------------------------------------+
126-
127-
128-
Superset::Dashboard::Get.call(1) # same as Superset::Dashboard::Get.new(1).list
129-
+----------------------------+
130-
| World Banks Data |
131-
+----------------------------+
132-
| Charts |
133-
+----------------------------+
134-
| % Rural |
135-
| Region Filter |
136-
| Life Expectancy VS Rural % |
137-
| Box plot |
138-
| Most Populated Countries |
139-
| Worlds Population |
140-
| Worlds Pop Growth |
141-
| Rural Breakdown |
142-
| Treemap |
143-
| Growth Rate |
144-
+----------------------------+
145-
64+
More examples [listed here](https://github.com/rdytech/superset-client/tree/develop/doc/usage.md)
14665

147-
```
148-
## Optional Credential setup for Embedded User
14966

150-
Primary usage is for api calls and/or for guest token retrieval when setting up applications to use the superset embedded dashboard workflow.
67+
## Duplicating Dashboards
15168

152-
The Superset API users fall into 2 categories
153-
- a user for general api calls to endpoints for Dashboards, Datasets, Charts, Users, Roles etc.
154-
ref `Superset::Credential::ApiUser`
155-
which pulls credentials from `ENV['SUPERSET_API_USERNAME']` and `ENV['SUPERSET_API_PASSWORD']`
69+
The Primary motivation behind this gem was to use the Superset API to duplicate dashboards, charts, datasets across multiple database connections.
15670

157-
- a user for guest token api call to use when embedding dashboards in a host application.
158-
ref `Superset::Credential::EmbeddedUser`
159-
which pulls credentials from `ENV['SUPERSET_EMBEDDED_USERNAME']` and `ENV['SUPERSET_EMBEDDED_PASSWORD']`
71+
Targeted use case was for superset embedded functionality implemented in a application resting on multi tenanted database setup.
16072

73+
See examples in [Duplicate Dashboards](https://github.com/rdytech/superset-client/tree/develop/doc/duplicate_dashboards.md)
16174

162-
### Fetch a Guest Token for Embedded user
16375

164-
Assuming you have setup your Dashboard in Superset to be embedded and that your creds are setup in
165-
`ENV['SUPERSET_EMBEDDED_USERNAME']` and `ENV['SUPERSET_EMBEDDED_PASSWORD']`
76+
## Contributing
16677

167-
```
168-
Superset::GuestToken.new(embedded_dashboard_id: '15').guest_token
169-
=> "eyJ0eXAiOi............VV4mrMfsvg"
170-
```
78+
- Fork it
79+
- Create your feature branch (git checkout -b my-new-feature)
80+
- Commit your changes (git commit -am 'Add some feature')
81+
- Push to the branch (git push origin my-new-feature)
82+
- Create new Pull Request
17183

172-
## Releasing a new version
17384

174-
On develop branch make sure to update `Superset::VERSION` and `CHANGELOG.md` with the new version number and changes.
175-
Build the new version and upload to gemfury.
176-
177-
`gem build superset.gemspec`
17885

17986
### Publishing to RubyGems
18087

18188
WIP .. direction is for this gem to be made public
18289

183-
### ReadyTech private Gemfury repo
184-
185-
ReadyTech hosts its own private gemfury remote repo.
186-
187-
Get the latest develop into master
188-
189-
git checkout master
190-
git pull
191-
git fetch
192-
git merge origin/develop
193-
194-
Tag the version and push to github
195-
196-
git tag -a -m "Version 0.1.0" v0.1.0
197-
git push origin master --tags
198-
199-
Push to gemfury or upload the build manually in the gemfury site.
200-
201-
git push fury master
202-
20390
## License
20491

20592
The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

‎bin/console‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ end
4545

4646
unless ENV['SUPERSET_HOST'] && ENV['SUPERSET_API_USERNAME'] && ENV['SUPERSET_API_PASSWORD']
4747
puts "Missing environment variables. Check your .env file"
48-
puts "Please set each value for SUPERSET_HOST, SUPERSET_API_USERNAME, and SUPERSET_API_PASSWORD values"
48+
puts "All env vars are required for SUPERSET_HOST, SUPERSET_API_USERNAME, and SUPERSET_API_PASSWORD values"
4949
puts "Refer to ./doc/setting_up_personal_api_credentials.md for more info"
5050
exit
5151
end
@@ -63,11 +63,13 @@ end
6363

6464
# general help to list all superset classes
6565
def superset_class_list
66-
puts " ---- Listing Superset Classes ----- "
66+
puts " ---- Listing Superset ruby client API Classes ----- "
6767
list_classes(Superset)
6868
end
69+
alias :sshelp :superset_class_list
6970

7071
puts "\n >>> Welcome to the Superset Ruby API Client <<< \n\n"
72+
puts "\n >>> list all available classes with 'sshelp' <<< \n\n"
7173
puts "Your accessible Superset Database connections are: Superset::Database::List.call"
7274

7375
Superset::Database::List.call

‎doc/publishing.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# Publishing
2+
3+
The team at ReadyTech currently manages the gem and new version releases.
4+
5+
As per demand / usage of the public gem, the team at ReadyTech will soon move to primarily hosting
6+
the gem on RubyGems.
7+
8+
Until then, ReadyTech will continue to host a private Gemfury version as well as RubyGems.
9+
10+
11+
## ReadyTech private Gemfury repo
12+
13+
### Releasing a new version
14+
15+
On develop branch make sure to update `Superset::VERSION` and `CHANGELOG.md` with the new version number and changes.
16+
17+
Build the new version and upload to gemfury.
18+
19+
`gem build superset.gemspec`
20+
21+
### Publish to Gemfury
22+
23+
ReadyTech hosts its own private gemfury remote repo.
24+
25+
Get the latest develop into master
26+
27+
git checkout master
28+
git pull
29+
git fetch
30+
git merge origin/develop
31+
32+
Tag the version and push to github
33+
34+
git tag -a -m "Version 0.1.0" v0.1.0
35+
git push origin master --tags
36+
37+
Push to gemfury or upload the build manually in the gemfury site.
38+
39+
git push fury master

‎doc/setting_up_personal_api_credentials.md‎

Lines changed: 43 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -26,17 +26,19 @@ Starting a ruby console with `bin/console` will auto load the env vars.
2626

2727
If your Superset instance is setup to authenicate via SSO then your authenticating agent will most likely have provided a username for you in the form of a UUID value.
2828

29-
This is easily retrieved on you User Profile page in Superset.
29+
This is easily retrieved on your user profile page in Superset.
3030

31-
Optionally use jinja template macro in sql lab.
31+
Optionally use the jinja template macro in sql lab.
3232

3333
```
3434
select '{{ current_username() }}' as current_username;
3535
```
3636

37+
Then plug your username in to the .env file.
38+
3739
## Creating / Updating your password via Swagger interface
3840

39-
A common setup is to use SSO to enable user access in Superset. This would mean your authenticating agent is your SSO provider service ( ie Azure ) and most likely you do not have / need a password configured for your Superset user for GUI access.
41+
A common setup is to use SSO to enable user access in Superset. This would mean your authenticating agent is your SSO provider service ( ie Azure etc ) and most likely you do not have / need a password configured for your Superset user for GUI access.
4042

4143
If this is the case, you will need to add your own password via hitting the superset API using the swagger interface.
4244

@@ -50,7 +52,7 @@ select '{{ current_user_id() }}' as current_user_id;
5052
```
5153
- ask your superset admin to tell you what your personal superset user id is.
5254

53-
Once you have your user id value, open the Swagger API page on you superset host.
55+
Once you have your user id value, open the Swagger API page on your superset host.
5456
`https://{your-superset-host}/swagger/v1`
5557

5658
Scroll down to the 'Security Users' area and find the PUT request that will update your users record.
@@ -78,7 +80,7 @@ Given some local development requirements where you have to access multiple supe
7880
Just set the overall superset environment in `.env`
7981

8082
```
81-
# .env file holding one setting for the overall superset environment
83+
# .env file holding one setting for the superset environment your accessing
8284
SUPERSET_ENVIRONMENT='staging'
8385
```
8486

@@ -101,11 +103,22 @@ SUPERSET_API_USERNAME="production-user-here"
101103
SUPERSET_API_PASSWORD="set-password-here"
102104
```
103105

104-
The command `bin/console` will then load your env file depending on the value in ENV['SUPERSET_ENVIRONMENT'] from the primary `.env`.
106+
And again, for localhost if required to perform api call in you local dev environment.
107+
Create a new file called `.env-localhost` that holds your superset development host and credentials.
108+
109+
```
110+
# specific settings for the superset localhost env
111+
SUPERSET_HOST="http://localhost:8080/"
112+
SUPERSET_API_USERNAME="dev-user-here"
113+
SUPERSET_API_PASSWORD="set-password-here"
114+
```
115+
116+
117+
The command `bin/console` will then load your env file depending on the value in ENV['SUPERSET_ENVIRONMENT'] from the primary `.env` file.
105118

106119
When you need to switch envs, exit the console, edit the .env to your desired value, eg `production`, then open a console again.
107120

108-
Bonus is the Pry prompt will now also include the `SUPERSET_ENVIRONMENT` value.
121+
The ruby prompt will now also include the `SUPERSET_ENVIRONMENT` value.
109122

110123
```
111124
bin/console
@@ -122,6 +135,29 @@ Happi: GET https://your-staging-superset-host.com/api/v1/dashboard/?q=(filters:!
122135
+----+------------------+-----------+------------------------------------------------------------------+
123136
```
124137

138+
## Optional Credential setup for Embedded User
139+
140+
Primary usage is for api calls and/or for guest token retrieval when setting up applications to use the superset embedded dashboard workflow.
141+
142+
The Superset API users fall into 2 categories
143+
- a user for general api calls to endpoints for Dashboards, Datasets, Charts, Users, Roles etc.
144+
ref `Superset::Credential::ApiUser`
145+
which pulls credentials from `ENV['SUPERSET_API_USERNAME']` and `ENV['SUPERSET_API_PASSWORD']`
146+
147+
- a user for guest token api call to use when embedding dashboards in a host application.
148+
ref `Superset::Credential::EmbeddedUser`
149+
which pulls credentials from `ENV['SUPERSET_EMBEDDED_USERNAME']` and `ENV['SUPERSET_EMBEDDED_PASSWORD']`
150+
151+
152+
### Fetch a Guest Token for Embedded user
153+
154+
Assuming you have setup your Dashboard in Superset to be embedded and that your creds are setup in
155+
`ENV['SUPERSET_EMBEDDED_USERNAME']` and `ENV['SUPERSET_EMBEDDED_PASSWORD']`
156+
157+
```
158+
Superset::GuestToken.new(embedded_dashboard_id: '15').guest_token
159+
=> "eyJ0eXAiOi............VV4mrMfsvg"
160+
```
125161

126162

127163

0 commit comments

Comments
 (0)