Full API and database documentation

[SeanAdams]

Given the need for administrators to be able to perform analysis and monitoring on server performance; user usage etc - it is necessary to provide full documentation for both the API and the database underlying the server so that admins can use this to good effect.

Ref: https://community.alteryx.com/t5/Alteryx-Server-Discussions/Server-API-Download-packages-for-surveil...

Although very limited documentation is available on the server API (https://gallery.alteryx.com/api-docs) what we're looking for is a much more fully formed and navigable experience like some of the examples below.

• https://onlinehelp.tableau.com/current/server/en-us/data_dictionary.html
• https://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api.htm%3FTocPath%3D___...
• https://community.lithium.com/t5/Developer-Documentation/bd-p/dev-doc-portal?section=commv2

This will make building helper processes substantially easier; as well as allow admins to fully manage their environment.

Many thanks

S

cc: @HeatherMHarris @revathi @AshwiniChezhiyan @LizaNemchynova

[AshwiniChezhiyan]

+1 for this idea. This will definitely be helpful for admins, as we manage large number of canvases and would like to get insights from our environment faster!

[TanyaS]

As we finish up systemic changes to the Server product, we'll evaluate endpoints to determine if they should be made public. This will be an ongoing effort in Server, and is not likely to be addressed in a single release.

That being said, as we work to determine the best strategy for our public endpoints, it would be great to follow up with those who are interested in what should be made available. I'll post here in the future when looking for customer views into what would be most beneficial.

Thanks,

Tanya

[SeanAdams]

Thank you Tanya,

The reason why there's a need for API endpoints is that in a large installation, much of this needs to be automated to manage the scale.   Given the variety of your client base, you cannot possibly be expected to do every kind of integration to enterprise entitlement systems; workflows; etc - so the best route is to provide clearly documented API endpoints so that we can all perform this integration internally.    NOTE: it would be important as Alteryx moves to Server.NEXT that these endpoints are maintained because firms will have made an investment in integrating their internal systems to these points.

Requested changes / additions:

(copied our Alteryx team to see what I've missed)

promotion or permissioning of assets:

• Change owner (needed for control of leavers / movers)
• Change permissions on an asset (so that this can be done programatically via workflow as part of entitlement process or migration to prod)
  • This would apply to any asset type - an application; a collection etc
• Create / amend scheduling
• Send to another server: This is an end-point that allows you to promote an asset to another Alteryx server, carrying the app ID with it so that the same App ID will be consistent across servers; and maintaining versioning in each env
• Create / amend collection
• List of Orphaned assets - assets which are owned by non-current or removed users (any asset type in the server)

Server Monitoring:

• Backlog in queue currently (execution queue depth on the controller)
• Canvas errors & warnings (both a list by time; and by appID)
• Can you please change the Workflow job to include a parameter to filter by modified date.   This is important for surveillance of changes.    Just to make this easy, perhaps just add modified-date filtering to all the list-type API endpoints (such as Schedules; Collections; etc) (http://localhost/gallery/api-docs/#!/admin-workflows.json/GetAppsGET)
• Canvas run history by version.     The goal here is to see if people are actually camping in our UAT environment; and using this as if it is a prod env
• Longest running canvasses
• Canvas Delays from Schedule
• Worker health stats such as:
  • Occupancy (degree to which this worker is being used)
  • CPU utilisation (most of our workers run at less than 50% CPU even when fully loaded)
  • Disk & Network utilisation 

Desktop Monitoring:

• Canvases run on desktop by version.    Again, the goal here is to see if people are camping out on the desktop - and the key is looking for a canvas which is run many times without being changed.

API Integration Assistance:

• For Server admins - it would be great if Alteryx provided an Admin toolkit which gave administrators pre-built integrator tools that they could use to do many of these automations

API Documentation Generally:

Could you consider adding to the documentation in a few ways:

• Add definition of the field types; or expected values etc
  • an example is the new auditLog endpoint (http://localhost/gallery/api-docs/#!/admin-workflows.json/GetPagedAuditLogGET) which requires an EntityType string, except there does not appear to be any definition of what the valid options are for this input
• Add definition of the output fields so that people can interpret and use the results
• A few worked examples (again, like the Tableau API spec above)
• Add definition of valid filters on these API calls - for example, when using the Workflows endpoint, we would want to look for workflows that have changed; or workflows where the owner is X; etc   This can be done simply by specifying a few filter parameters; and providing a simple way for people to request others in later versions with the use-cas

+  @Hemanth @marydest24 @Shreyasi @Sotoll @Kosi @revathi @Bethanyturner012  

[KevinP]

@SeanAdams There is another product idea dedicated to documenting the MongoDB schema (see link below). I am undertaking an initiative to update the available documentation and extended it to cover the a much more extensive portion of the schema (possibly the entire schema). This will be an ongoing effort and I do not have an ETA at this time, but you can expect this documentation to be available for future releases.

https://community.alteryx.com/t5/Alteryx-Server-Ideas/Mongo-Database-Dictionary/idi-p/475043

[SeanAdams]

Thank you @KevinP - I think a lot of people will benefit from a clear DB Schema definition for the underlying Mongo store.

[KylieF]

Thank you for your idea! I'm updating this idea to the Revisit status, however this revisit status really only applies to one part of this idea. We currently are unable to place the API documentation on our road map due to several back end restrictions on how our documentation is built.  The database documentation however is being worked on and we should potentially see this feature in a future release.

[KevinP]

@SeanAdams We have officially released the MongoDB documentation. You can find it in the online help or directly via the following links:

2019.4 MongoDB Schema Reference - https://help.alteryx.com/20194/server/mongodb-schema-reference
2020.1 MongoDB Schema Reference - https://help.alteryx.com/20201/server/mongodb-schema-reference

[KylieF]

@SeanAdams 

Since this idea touches on two unique feature requests, and to help product better categorize community ideas, I'd like either the Database or API documentation portions off into a separate idea so they can be updated accordingly. Would you be able to submit the API documentation idea as a separate idea? That way we can push this idea to implemented for the Database documentation and evaluate the API documentation potion separately.

[JohnPelletier]

Hi folks,

While the API ideas are helpful, it's necessary to focus here on the documentation of the database schema so we can call this resolved. As @KevinP mentioned above, we now have the schema as originally requested.

We have plans to work on the APIs in a near-term future release, so please suggest your best API ideas in a separate thread. Thanks!

[KylieF]

Thank you for your feedback and idea!

We've re-evaluated this idea and have determined we're able to include it on the near term road map, however a complete API documentation is a fairly large undertaking. Due to this it may take some time and several releases for us to implement it completely. We appreciate your patience while we work on this documentation!