adding more info to the API reference page by d45 · Pull Request #183 · tableau/server-client-python

d45 · Apr 19, 2017

This PR is to add more information about the TSC library API methods and classes. You can preview the updated docs here: https://d45.github.io/server-client-python/docs/api-ref

The PR also includes an update to the navigation pane (docs_menu.html) for the new sections. Looks like there is a minor merge conflict with that file (spaces or something).

NOTE: Merging into master so that the update goes live when the PR is approved.
I could also merge into the Dev branch, if you prefer. That would require another move to get the files to master. Squash and merge if it seems OK after review. Thanks.

d45 · Apr 19, 2017

OK. I spoke too soon. The api-ref.md file has some conflicts. The new version should replace the old.

graysonarts

My biggest question is around ordering of the api reference. I feel like there is an inherent hierarchy in the design of the library and listing the api reference in alphabetic order doesn't feel like the right thing to me.

If I was reading this documentation, I would want the first thing first: the server object. Then auth since you have to sign in before every thing else. Maybe if it was broken into to sections: "Top-level" and "Resources" or something like that?

graysonarts · Apr 20, 2017

docs/docs/api-ref.md

@@ -5,257 +5,3008 @@ layout: docs

 <div class="alert alert-info">
    <b>Important:</b> More coming soon! This section is under active construction and might not reflect all the available functionality of the TSC library.
-    Until this reference is completed, we have noted the source files in the TSC library where you can get more information for individual endpoints.
-</div>
+    <!--- Until this reference is completed, we have noted the source files in the TSC library where you can get more information for individual endpoints. --->


Just delete the comment. We have version control if we need to revive this line.

I'll take care of the quick fixes in this PR (against master). I hear you about the ordering of the API references. I will look into that after I switch to development as base.

graysonarts · Apr 20, 2017

docs/docs/api-ref.md

+The TSC API reference is organized by resource. The TSC library is modeled after the REST API. The methods, for example, `workbooks.get()`, correspond to the endpoints for resources, such as [workbooks](#workbooks), [users](#users), [views](#views), and [data sources](#data-sources). The model classes (for example, the [WorkbookItem class](#workbookitem-class) have attributes that represent the fields (`name`, `id`, `owner_id`) that are in the REST API request and response packages, or payloads. 
+
+|:---  |  
+| **Note:**  Some methods and features provided in the REST API might not be currently available in the TSC library.  In addition, the same limitations apply to the TSC library that apply to the REST API with respect to resources on Tableau Server and Tableau Online. For more information, see the [Tableau Server REST API Reference](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#API_Reference%3FTocPath%3DAPI%2520Reference%7C_____0){:target="_blank"}.|


I would add "and vice-versa" because we have functionality in TSC that isn't released to the public yet (though they are in betas)

graysonarts · Apr 20, 2017

docs/docs/api-ref.md

+
+* TOC  
+{:toc }
+<!-- {:toc ::options toc_levels="1,2"} -->


delete comments

Removed the comments. Leftover from an experiment with kramdown and the toc_levels in the toc macro.

graysonarts · Apr 20, 2017

docs/docs/api-ref.md

 ```
+The `TableauAuth` class contains the attributes for the authentication resources. The `TableauAuth` class defines the information you can set in a  request or query from Tableau Server. The class members correspond to the attributes of a server request or response payload. To use this class, create a new instance, supplying user name, password, and site information if necessary, and pass the request object to the [Auth.sign_in](#auth.sign-in) method.


Probably include a note about other authentication schemes may be added in the future (e.g. oauth)

graysonarts · Apr 20, 2017

docs/docs/api-ref.md

+:--- | :---   
+`username` | The name of the user whose credentials will be used to sign in.   
+`password` | The password of the user.     
+`site_id` | This corresponds to the `contentUrl` attribute in the Tableau REST API. The `site_id` is the portion of the URL that follows the `/site/` in the URL. For example, "MarketingTeam" is the `site_id` in the following URL *MyServer*/#/site/**MarketingTeam**/projects. To specify the default site on Tableau Server, you can use an empty string **' '**.  For Tableau Online, you must provide a value for the `site_id`.  


your empty string contains a space.

Good point. I'll correct that and spell it out.

graysonarts · Apr 20, 2017

docs/docs/api-ref.md

+Name | Description  
+:--- | :--- 
+`datasource_id` |  The identifier (`id`) for the the `DatasourceItem` that you want to download from the server. 
+`filepath` |  (Optional) Downloads the file to the location you specify. If no location is specified (the default is `Filepath=None`), the file is downloaded to the current working directory. 


We should mention no_extract as a parameter

Added it. I'll add no_extract to workbooks.download too

…ta sources)

graysonarts · Apr 20, 2017

docs/docs/api-ref.md

 `datasource_id` |  The identifier (`id`) for the the `DatasourceItem` that you want to download from the server. 
 `filepath` |  (Optional) Downloads the file to the location you specify. If no location is specified (the default is `Filepath=None`), the file is downloaded to the current working directory. 
-
+`no_extract` | (Optional) Specifies whether to download the file without the extract. When the data source has an extract, if you set the parameter `no_extract=True`, the extract is not included. You can use this parameter to improve performance if you are downloading data sources that have large extracts. The default is to include the extract, if present (`no_extract=False`). 


we should mention that this is REST v2.5+.

Good point. We should probably add the "available in REST version XX" for all of these. Or some.

graysonarts

Other than that one small change about no_extract, looks good.

t8y8

I read through half and had some comments.

Overall pretty solid, lots of nit picks on my part. I'll review the second half soonish (sorry it took me so long)

t8y8 · Apr 20, 2017

docs/docs/api-ref.md


 ## Authentication

-Source files: server/endpoint/auth_endpoint.py, models/tableau_auth.py
+You can use the TSC library to manage authentication, so you can sign in and sign out of Tableau Server and Tableau Online. The authentication resources for Tableau Server are defined in the `TableauAuth` class and they correspond to the authentication attributes you can access using the Tableau Server REST API. 


You don't manage authentication, you sign in out sign out -- I could misread this to think it let's me manipulate other credentials on Server or auth settings or something.

No problem. It took me a while to get back on this. I just made another commit and added the update_connections for workbooks. That is what caused the merge conflict.

OK. Good point. I managed to remove the managed and simplified it.

t8y8 · Apr 20, 2017

docs/docs/api-ref.md

 ```
+The `TableauAuth` class contains the attributes for the authentication resources. The `TableauAuth` class defines the information you can set in a  request or query from Tableau Server. The class members correspond to the attributes of a server request or response payload. To use this class, create a new instance, supplying user name, password, and site information if necessary, and pass the request object to the [Auth.sign_in](#auth.sign-in) method.  


I'm a little skeptical calling it an authentication 'resource'. Not a big one, I'd actually just call it an object or credentials or something.

Yes. I wasn't sure about that either. My wording here is pretty clumsy. I'll revise. Gotta run right now, but I will get back to it.

cut it down to this:
The TableauAuth class defines the information you can set in a sign-in request. The class members correspond to the attributes of a server request or response payload. To use this class, create a new instance, supplying user name, password, and site information if necessary, and pass the request object to the Auth.sign_in method.

t8y8 · Apr 20, 2017

docs/docs/api-ref.md

-self.server.sites.create(new_site)
+import tableauserverclient as TSC
+
+# create a auth request


t8y8 · Apr 20, 2017

docs/docs/api-ref.md

+# create an instance for your server
+server = TSC.Server('http://SERVER_URL')
+
+# call the sign-in method with the request


You call sign in with the object/resource/whatever-you-pick not the request, you're making a request

t8y8 · Apr 20, 2017

docs/docs/api-ref.md


-### Get Sites
+The method takes care of invalidating the authentiction token. For more information, see [Sign in and Out](sign-in-out).


this method? or the method?

Changed to "The sigh_out() method ... "

t8y8 · Apr 20, 2017

docs/docs/api-ref.md

+  ...
+
+  project_id = '3a8b6148-493c-11e6-a621-6f3499394a39'
+  file_path = 'C:\\temp\\WorldIndicators.tde'


I prefer raw strings r'C:\temp\WorldIndicators.tde' -- style choice though

I'll go with that. Thanks.

t8y8 · Apr 20, 2017

docs/docs/api-ref.md

+    ...
+
+    single_datasource = TSC.DatasourceItem('test', '1d0304cd-3796-429f-b815-7258370b9b74')
+    # need to specify the ID - this is a workaround. 


I don't like workaround in the docs :( why is this necessary? /cc @RussTheAerialist

That is, what's this sample showing, do we need to demonstrate it that way

Yeah, I'm not sure what you are trying to show here? In this case, that workaround was probably specifically to enable the test scenario and not a preferred way of doing something

Oh wait, if I look below. In this case, we want to "get the datasource by id" from the server object before updating it. The current implementation in this section is definitely not what we want people to do.

Yikes. Good catch. That is a placeholder example from the test code.

replaced that example with this:

# get the data source item to update datasource = server.datasources.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b') # do some updating datasource.name = 'New Name' # call the update method with the data source item updated_datasource = server.datasources.update(datasource)

t8y8 · Apr 20, 2017

docs/docs/api-ref.md

 ```

-### Get Views for a Workbook
+The `GroupItem` class contains the members or attributes for the view resources on Tableau Server. The `GroupItem` class defines the information you can request or query from Tableau Server. The class members correspond to the attributes of a server request or response payload.


What are members?
I think it's just attributes :P

yep. Fixed that. Also changed "view resources" to "group resources" - copy and paste error.

t8y8 · Apr 20, 2017

docs/docs/api-ref.md

+# The id for Ian is '59a8a7b6-be3a-4d2d-1e9e-08a7b6b5b4ba'
+
+# add Ian to the second group
+  server.groups.add_user(all_groups[1], '59a8a7b6-be3a-4d2d-1e9e-08a7b6b5b4ba')


Whenever possible we should avoid the [subscript] notation in example because it's not obvious what it means. We can always pop it from the list and give it a name

Good point. I was just trying to get something to work and stopped at that. I will update these instances if I can.

Rats! -- I goofed on some of these examples. We don't have a groups.get_by_id() method.
Probably thinking of it as way to get around indexing []. I guess I didn't test those.

t8y8 · Apr 20, 2017

docs/docs/api-ref.md

+# call the create method
+  newgroup = server.groups.create(newgroup)
+
+# print the names of the groups on the server


Without Pager this is only the first 100 groups

added the 100 limit to the comment

…ed some connectionitem info

…source update example

t8y8 · Apr 21, 2017

Text is looking great, only thing I have left (before maybe a final pass) is that I agree w/ @RussTheAerialist that the organization is a bit odd. Filter/Sort inside the list alphabetically is very is jointed from their actual use.

d45 · Apr 21, 2017

Thanks for digging into this. Your review has been super helpful and has uncovered a lot of issues. I finally ran spell check and took care of some ridiculous 'errrors". About the organization. I agree that it doesn't make sense if you are looking at it from a "how do I do xx" perspective. Ideally, the modules would be separate files, so it would be easy to sort them around in a more logical manner (models, endpoints,etc). We don't have that at the moment. Because it is a long, long file (like 70 pages in Word) I think the alphabetical approach is only way of making it almost useful for finding stuff and scrolling around. But just barely. Breaking the file up into sections makes sense. Anyway... what we really need is to add more to the "Getting Started" pages. That way we could described how the library is organized and what you need to do to begin using it (as Russell said, starting with the server and working out to the resources. If we do that, how the reference pages are organized won't matter as much. Oh, it looks like the merge conflict is just with the workbooks update method. I added that, so I think that we should be good.

…

On Fri, Apr 21, 2017 at 3:38 PM, Tyler Doyle ***@***.***> wrote: Text is looking great, only thing I have left (before maybe a final pass) is that I agree w/ @RussTheAerialist <https://github.com/RussTheAerialist> that the organization is a bit odd. Fillter/Sort inside the list alphabetically is very is jointed from their actual use. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#183 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AKON_SjJtjU20KTveVZFUhZNXAJzlwTfks5ryTABgaJpZM4NCXcf> .

* adding to ref pages; saving progress so far * Check in to save progress-o * Another chekin' for the cause * Check in more stuff; added api buckets in docs menu * Updated with users, groups; snapshot * Check in more changes to ref pages, minor fix for docs menu * more updates; formatting fixes, etc. * um updates, workbooks in prog, etc. * getting there, mostly done. * sorted, added filters, requests, etc. * ready for review.... * update to the left nav for new classes * Added sites.get_by_name; added quotes to sever.version number example * updates from tech review; added no_extract to downloads (workbook, data sources) * Added workbooks.update_connections (the cause of merge conflict); fixed some connectionitem info * tech review fixes, removed groups.get_by_id from examples, fixed datasource update example * Ran spellcheck, fixed misc errors

d45 added 13 commits March 22, 2017 16:10

adding to ref pages; saving progress so far

7901ae4

Check in to save progress-o

c6d0a25

Another chekin' for the cause

5ae1a3c

Check in more stuff; added api buckets in docs menu

f0c5d51

Updated with users, groups; snapshot

f52429a

Check in more changes to ref pages, minor fix for docs menu

fef93e4

more updates; formatting fixes, etc.

f9a1971

um updates, workbooks in prog, etc.

2920682

getting there, mostly done.

cb3962e

sorted, added filters, requests, etc.

45310dc

ready for review....

9e2e795

update to the left nav for new classes

bb63aed

Added sites.get_by_name; added quotes to sever.version number example

a1a5c12

graysonarts reviewed Apr 20, 2017

View reviewed changes

updates from tech review; added no_extract to downloads (workbook, da…

4577607

…ta sources)

d45 changed the base branch from master to development April 20, 2017 21:26

graysonarts reviewed Apr 20, 2017

View reviewed changes

graysonarts approved these changes Apr 20, 2017

View reviewed changes

t8y8 suggested changes Apr 20, 2017

View reviewed changes

d45 added 3 commits April 20, 2017 16:31

Added workbooks.update_connections (the cause of merge conflict); fix…

3f8df49

…ed some connectionitem info

tech review fixes, removed groups.get_by_id from examples, fixed data…

70fa4a0

…source update example

Ran spellcheck, fixed misc errors

248a172

Merge branch 'development' into master

651341b

graysonarts merged commit 27b5917 into tableau:development Apr 26, 2017

		```
		The `TableauAuth` class contains the attributes for the authentication resources. The `TableauAuth` class defines the information you can set in a request or query from Tableau Server. The class members correspond to the attributes of a server request or response payload. To use this class, create a new instance, supplying user name, password, and site information if necessary, and pass the request object to the [Auth.sign_in](#auth.sign-in) method.


		### Get Sites
		The method takes care of invalidating the authentiction token. For more information, see [Sign in and Out](sign-in-out).

Search code, repositories, users, issues, pull requests...

Conversation

d45 commented Apr 19, 2017

Uh oh!

d45 commented Apr 19, 2017

Uh oh!

graysonarts left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

graysonarts left a comment

Choose a reason for hiding this comment

Uh oh!

t8y8 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

graysonarts Apr 20, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

d45 Apr 21, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

graysonarts Apr 20, 2017 •

edited

Loading

d45 Apr 21, 2017 •

edited

Loading

t8y8 commented Apr 21, 2017 •

edited

Loading